diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/sdk/tools')
| -rw-r--r-- | files/fr/mozilla/add-ons/sdk/tools/cfx_to_jpm/index.html | 192 | ||||
| -rw-r--r-- | files/fr/mozilla/add-ons/sdk/tools/index.html | 13 | ||||
| -rw-r--r-- | files/fr/mozilla/add-ons/sdk/tools/jpm/index.html | 600 |
3 files changed, 805 insertions, 0 deletions
diff --git a/files/fr/mozilla/add-ons/sdk/tools/cfx_to_jpm/index.html b/files/fr/mozilla/add-ons/sdk/tools/cfx_to_jpm/index.html new file mode 100644 index 0000000000..e8b50f5006 --- /dev/null +++ b/files/fr/mozilla/add-ons/sdk/tools/cfx_to_jpm/index.html @@ -0,0 +1,192 @@ +--- +title: De cfx à jpm +slug: Mozilla/Add-ons/SDK/Tools/cfx_to_jpm +translation_of: Archive/Add-ons/Add-on_SDK/Tools/cfx_to_jpm +--- +<div class="note"> +<p>L'Add-on SDK inclut un outil de ligne de commande que vous utilisez pour initialiser, exécuter, tester, et empaqueter des add-ons. L'outil actuel est appelé jpm, il est basé sur <a href="http://nodejs.org/" title="http://nodejs.org/"> Node.js </a>. Il remplace l'outil cfx.</p> + +<p>Vous pouvez utiliser jpm à partir de Firefox 38.</p> + +<p>Cet article met en évidence les principales différences entre cfx et jpm.</p> +</div> + +<p><span class="seoSummary">Un guide pour travailler avec jpm si vous êtes déjà familier avec cfx.</span></p> + +<h2 id="Installation">Installation</h2> + +<p>cfx est basée sur Python et est distribué comme un fichier zip. jpm est baser sur Node.js qui est <a href="https://www.npmjs.org/package/jpm" title="https://www.npmjs.org/package/jpm"> distribué par npm </a>. Donc, pour jpm vous n'avez pas besoin de Python, mais vous avez besoin npm.</p> + +<p>Pour obtenir les mises de cfx vous deviez télécharger et extraire un fichier zip, tandis que pour obtenir la nouvelle version de jpm, utilisez <a href="https://docs.npmjs.com/cli/update" title="https://www.npmjs.org/doc/api/npm-update.html"> <code>npm update</code> </a>.</p> + +<p>Pour obtenir des instructions d'installation de jmp, consultez la section de l' <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/jpm#Installation" title="/fr/Add-ons/SDK/Tools/jpm#Installation">Installation</a> dans la référentiel de jmp.</p> + +<h2 id="Activation">Activation</h2> + +<p>Vous devez appeler <code>cfx activate</code> avant de pouvoir utiliser cfx, et cela ne fonctionne que dans le shell de commande de courant:. Si vous ouvrez un nouveau shell, vous devez appeler <code>activate</code> de nouveau</p> + +<p>Avec jpm, pas d'activation. Une fois qu'il est installé, vous pouvez simplement l'utiliser.</p> + +<h2 id="Incompatibilités">Incompatibilités</h2> + +<p>Dans la plupart cas, les add-ons créés avec cfx fonctionnent bien avec jpm. Cependant, il y a quelques différences que vous devez connaitre.</p> + +<h3 id="Add-on_ID">Add-on ID</h3> + +<p>L'ID de add-on est l'identifiant unique de votre add-on. Dans un xpi, c'est le<a href="https://developer.mozilla.org/fr/docs/Mozilla/Add-ons/Install_Manifests#id" title="https://developer.mozilla.org/en/install.rdf#id"> champ ID dans le fichier Manifest d'instalation de l'add-on</a> (install.rdf).</p> + +<p>L'identifiant est utilisé à des fins variées. Par exemple: <a href="http://addons.mozilla.org" title="http://addons.mozilla.org">addons.mozilla.org</a> l'utilise pour distinguer entre les nouvelles add-ons et les mises à jour d'add-ons existantes, et le module <a href="https://developer.mozilla.org/fr/docs/Mozilla/Add-ons/SDK/High-Level_APIs/simple-storage" title="https://developer.mozilla.org/fr/Add-ons/SDK/High-Level_APIs/simple-storage"><code>simple-storage</code></a> l'utilise pour déterminer lesquelles des données stockées appartiennent à tel add-on.</p> + +<h4 id="Manipulation_avec_l'ID_cfx">Manipulation avec l'ID cfx</h4> + +<p>Lorsque vous utilisez cfx, l'ID est tiré du <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#id" title="/fr/Add-ons/SDK/Tools/package_json#id">champ <code>id</code> dans le fichier de package.json de l'add-on</a>. Vous pouvez éditer ce fichier pour créer votre propre identité, mais si vous ne le faites pas, cfx va le générer pour vous, ce qui va ressembler à quelque chose comme "<code>jid1-F3BoogbjQJE67A</code>". <a href="https://developer.mozilla.org/fr/docs/Mozilla/Add-ons/Install_Manifests#id" title="https://developer.mozilla.org/fr/Add-ons/Install_Manifests#id">L'ID Add-on doit être l'un des deux types suivant </a>: un GUID ou une chaîne qui comprend un symbole <code>"@"</code>. Le SDK ne prévoit que le dernier format, et si l'ID dans package.json ne contient pas de "@", cfx xpi ajouter "<code>@jetpack</code>" dans le champ de package.json, ce qui transforme l'ID de l'add-on.</p> + +<p>Donc: si vous n'avez jamais manipulé l'ID lors de l'utilisation cfx, alors la valeur dans le package.json de votre add-on sera quelque chose comme "<code>jid1-F3BoogbjQJE67A</code>", et l'ID correspondant dans la install.rdf sera "<code>jid1-F3BoogbjQJE67A@jetpack</code>".</p> + +<h4 id="Manipulation_d'ID_avec_jpm">Manipulation d'ID avec jpm</h4> + +<p>Lorsque vous créez un xpi avec <code>jpm xpi</code>:</p> + +<ul> + <li>si le package.json ne comprend pas un champ <code>id</code>, alor l'ID dans l'install.rdf à la valeur de la <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#name" title="/fr/Add-ons/SDK/Tools/package_json#name"> champ <code>name</code></a> Préfixé par "@".</li> + <li>si le package.json inclut un champ <code>id</code>, et il contient «@», alors l'écriture est la même dans install.rdf.</li> + <li>si le package.json inclut un champ <code>id</code>, sans "@", jpm XPI soulève une erreur et le xpi ne sera pas construit.</li> +</ul> + +<h4 id="Ce_que_vous_devez_faire">Ce que vous devez faire</h4> + +<p>Tout cela signifie que: <em> si votre package.json contient un champ id, et sa valeur ne contient pas «@», alors vous devez ajouter "@jetpack» lors du passage à jpm </em>.</p> + +<p>Si vous faites cela, l'ID de l'add-on sera la même que l'id utilisée avec cfx.</p> + +<h3 id="Point_d'entrée">Point d'entrée</h3> + +<p>Le point d'entrée de l'add-on est le fichier qui est exécutée lorsque l'add-on a besoin de s'initialiser: par exemple, au démarrage de Firefox, ou lorsque l'add-on est installé, activé, ou mis à niveau. Avec cfx, la valeur par défaut à "lib/main.js", même si elle peut être réglée sur un autre fichier en utilisant le <code>main</code> champ dans le package.json .</p> + +<p>Dans jpm, le point d'entrée par défaut est "index.js". Donc, lors de la commutation vers jpm:</p> + +<ul> + <li>renommez vos "main.js" en "index.js" et déplacez les de "lib" vers le plus haut niveau</li> + <li>ou ajouter un champ <code>main</code> dans package.json avec pour valeur "lib/main.js".</li> +</ul> + +<h3 id="Chargement_des_modules">Chargement des modules</h3> + +<p>L'outil jpm utilise la même logique que <a href="http://nodejs.org/api/modules.html#modules_all_together" title="http://nodejs.org/api/modules.html#modules_all_together"> Node.js </a> pour déterminer comment résoudre l'argument <code>require()</code>. Dans la plupart des cas, c'est la même <a href="/fr/docs/Mozilla/Add-ons/SDK/Guides/Module_structure_of_the_SDK" title="/fr/Add-ons/SDK/Guides/Module_structure_of_the_SDK">logique que cfx</a>. Cependant, il existe quelques différences, parce certaines compatibilités ont été retirées.</p> + +<h4 id="Requérir_à_des_modules_locaux">Requérir à des modules locaux</h4> + +<p>Supposons que votre add-on est <a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/Creating_Reusable_Modules" title="/fr/Add-ons/SDK/Tutorials/Creating_Reusable_Modules"> structuré en modules séparés </a>:</p> + +<ul class="directory-tree"> + <li>my-addon + <ul> + <li>lib + <ul> + <li>main.js</li> + <li>utils.js</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Lorsque vous voulez utiliser un module "utils.js" dans "main.js", vous devez utiliser un chemin relatif à "main.js", et le préfixer avec "./" pour indiquer que c'est un chemin relatif:</p> + +<pre class="brush: js">var utils = require("./utils");</pre> + +<p>Cependant, avec cfx vous êtes également autorisé à omettre le "./":</p> + +<pre class="brush: js">var utils = require("utils"); // this will not work with jpm!</pre> + +<p>Cette seconde forme ne fonctionnera pas avec jpm.</p> + +<h4 id="Requérir_des_modules_de_code_de_test">Requérir des modules de code de test</h4> + +<p>Similarly, suppose you've written some tests for your add-on:</p> + +<ul class="directory-tree"> + <li>my-addon + <ul> + <li>lib + <ul> + <li>my-addon.js</li> + </ul> + </li> + <li>test + <ul> + <li>test-my-addon-js</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Avec cfx, le code de "test-my-addon.js" peut importer "my-addon.js" en utilisant une déclaration de ce genre:</p> + +<pre class="brush: js">var my_addon = require("my-addon"); // ceci ne fonctionne pas avec jpm!</pre> + +<p>Avec jpm, vous devez spécifier le chemin vers «my-addon" explicitement, en utilisant un chemin relatif:</p> + +<pre class="brush: js">var my_addon = require("../lib/my-addon"); +</pre> + +<h3 id="Modules_tiers">Modules tiers</h3> + +<p>Le SDK a toujours soutenu les modules tiers: les développeurs peuvent écrire leurs propres modules qui étendent les API du SDK ou ajouter de nouvelles API, et d'autres add-on peuvent faire usage de ces modules de la même manière qu'ils utilisent les modules intégré au SDK.</p> + +<p>Dans jpm cette façon <a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox" title="/fr/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox"> d'utiliser des modules tiers </a> ne fonctionne plus. Au lieu de cela, jpm n'accepte que les modules tiers hébergés sur la npm, vous pouvez les utiliser en les installant à partir de la npm dans l'arbre de répertoire de votre add-on. Voir le tutoriel<a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/Using_third-party_modules_(jpm)" title="/fr/Add-ons/SDK/Tutorials/Using_third-party_modules_(jpm)"> utilisant des modules tiers avec jpm</a>.</p> + +<h2 id="Les_commandes_et_les_options_de_commande">Les commandes et les options de commande</h2> + +<h3 id="Commandes_définitivement_retiré">Commandes définitivement retiré</h3> + +<p>jpm ne soutient plus les <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/cfx#Internal_Commands" title="/fr/Add-ons/SDK/Tools/cfx#Internal_Commands">commandes cfx "interne"</a>.</p> + +<h3 id="Options_définitivement_retiré">Options définitivement retiré</h3> + +<p>jpm ne soutient plus :</p> + +<pre>--extra-packages +--use-config +--package-path +--pkgdir +--no-strip-xpi +--harness-option +--manifest-overload +--output-file +--templatedir +--keydir +--profiledir +--overload-modules +--static-args +--app +--no-run +--addons +--e10s +--logfile +--dependencies +--test-runner-pkg</pre> + +<p>Au lieu de <code>--profiledir</code> et de <code>--overload-modules</code>, utilisez <code>--profile</code> et <code>--overload</code></p> + +<h2 id="Champs_Package.json">Champs Package.json</h2> + +<p>Beaucoup de champs package.json <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json" title="/fr/Add-ons/SDK/Tools/package_json"> </a> sont des commandes implicites de cfx. Dans jpm, nous avons supprimé le soutien de certains de ces domaines, et travaillons toujours sur le soutien des autres.</p> + +<h3 id="Champs_définitivement_retiré">Champs définitivement retiré</h3> + +<ul> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#data">data</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#fullName">fullName</a> - use <a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#title">title</a> instead</li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#lib">lib</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#packages">packages</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#tests">tests</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tools/package_json#icon64">icon64</a></li> +</ul> + +<h2 id="Echappement_dans_Package.json">Echappement dans Package.json</h2> + +<p>Où avec cfx vous auriez dû échapper avec 2 voir 3 barres obliques inverses (\), jpm n'en a besoin que d'une.</p> + +<p> </p> diff --git a/files/fr/mozilla/add-ons/sdk/tools/index.html b/files/fr/mozilla/add-ons/sdk/tools/index.html new file mode 100644 index 0000000000..89f1db963b --- /dev/null +++ b/files/fr/mozilla/add-ons/sdk/tools/index.html @@ -0,0 +1,13 @@ +--- +title: Tools +slug: Mozilla/Add-ons/SDK/Tools +tags: + - Add-on SDK + - CFX + - JPM + - TopicStub +translation_of: Archive/Add-ons/Add-on_SDK/Tools +--- +<p>Les articles répertoriés ici fournissent une référence pour les outils du SDK:</p> + +<p>{{ LandingPageListSubpages ("/en-US/Add-ons/SDK/Tools", 7) }}</p> diff --git a/files/fr/mozilla/add-ons/sdk/tools/jpm/index.html b/files/fr/mozilla/add-ons/sdk/tools/jpm/index.html new file mode 100644 index 0000000000..c079f3b0b5 --- /dev/null +++ b/files/fr/mozilla/add-ons/sdk/tools/jpm/index.html @@ -0,0 +1,600 @@ +--- +title: jpm +slug: Mozilla/Add-ons/SDK/Tools/jpm +translation_of: Archive/Add-ons/Add-on_SDK/Tools/jpm +--- +<div class="note"> +<p>Vous pouvez utiliser <code>jpm</code> pour Firefox 38 et au-delà.</p> + +<p>Cet article est la référence pour jpm.</p> +</div> + +<p><span class="seoSummary">The Node-based replacement for <a href="/en-US/Add-ons/SDK/Tools/cfx">cfx</a>. Enables you to test, run, and package add-ons.</span></p> + +<p>Voir aussi le <a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29" title="/fr/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29">tutoriel jpm</a> pour débuter.</p> + +<p>jpm usage is:</p> + +<pre class="brush: bash">jpm [command] [options] +</pre> + +<p>jpm supports the following global options:</p> + +<pre class="brush: bash">-h, --help - show a help message and exit +-V, --version - print the jpm version number +</pre> + +<h2 id="Installation">Installation</h2> + +<p>jpm is distributed using the node package manager <a class="external external-icon" href="https://www.npmjs.org/package/jpm">npm</a>, so to get jpm you need to have npm installed, if you haven't already. npm is included in Node.js. To install npm, you can either visit <a class="external external-icon" href="http://nodejs.org/">nodejs.org</a> and download the latest binary or if you have a package manager like APT installed on your system, you might want to use this package manager to install npm. For example, if you are using an Ubuntu or Debian operating system, execute <code>sudo apt-get install nodejs </code>followed by <code>sudo apt-get install npm </code>in a terminal window.</p> + +<p>After that you can install jpm just as you would any other npm package:</p> + +<pre><code>npm install jpm --global</code></pre> + +<p>Depending on your setup, you might need to run this as an administrator:</p> + +<pre class="brush: bash"><code>sudo npm install jpm --global</code></pre> + +<p>Or, you can install jpm using git:</p> + +<pre>git clone https://github.com/mozilla-jetpack/jpm.git +cd jpm +npm install +npm link +</pre> + +<p><span style="line-height: 1.5;">À l'invite de commande, tapez:</span></p> + +<pre class="brush: bash"><code>jpm</code></pre> + +<p>You should see a screen summarizing the available jpm commands. Note that unlike cfx, jpm is available in every command prompt you start, as long as you installed it with the <code>--global</code> flag.</p> + +<p>If you get an error message saying <em>/usr/bin/env: node: No such file or directory</em> and you have installed nodejs through a package manager, nodejs may have been installed in the wrong directory. A <a href="http://stackoverflow.com/questions/20886217/browserify-error-usr-bin-env-node-no-such-file-or-directory">corresponding topic at stackoverflow.org</a> might help you to solve this problem. Basically, you can solve it by creating a symlink to the node:</p> + +<pre class="lang-js prettyprint prettyprinted"><code><span class="pln">sudo ln </span><span class="pun">-</span><span class="pln">s </span><span class="str">"$(which nodejs)"</span><span class="pln"> </span><span class="pun">/</span><span class="pln">usr</span><span class="pun">/</span><span class="pln">bin</span><span class="pun">/</span><span class="pln">node</span></code></pre> + +<h3 id="Problems">Problems?</h3> + +<p>If you don't see this, ask for help. SDK users and project team members discuss problems and proposals on the <a class="external external-icon" href="http://groups.google.com/group/mozilla-labs-jetpack/topics">project mailing list</a>. Someone else may have had the same problem you do, so try searching the list. You're welcome to post a question, too. You can also chat with other SDK users in <a class="external external-icon" href="http://mibbit.com/?channel=%23jetpack&server=irc.mozilla.org">#jetpack</a> on <a class="external external-icon" href="http://irc.mozilla.org/">Mozilla's IRC network</a>.</p> + +<h2 id="Command_reference">Command reference</h2> + +<p>There are six jpm commands:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td style="width: 20%;"><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_init"><code>jpm init</code></a></td> + <td>Create a skeleton add-on as a starting point for your own add-on.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_run"><code>jpm run</code></a></td> + <td>Launch an instance of Firefox with your add-on installed.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_test"><code>jpm test</code></a></td> + <td>Runs your add-on's unit tests.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_xpi"><code>jpm xpi</code></a></td> + <td>Package your add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file, which is the install file format for Firefox add-ons.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_post"><code>jpm post</code></a></td> + <td>Package your add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file, then post it to some url.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_watchpost"><code>jpm watchpost</code></a></td> + <td>Package your add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file whenever there is a file changed, and post that to some url.</td> + </tr> + <tr> + <td><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_sign"><code>jpm sign</code></a></td> + <td>Package your add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file, then retrieve a new XPI signed by Mozilla.</td> + </tr> + </tbody> +</table> + +<h3 id="jpm_init">jpm init</h3> + +<p>This command initializes a new add-on from scratch.</p> + +<p>Create a new directory, change into it, and run <code>jpm init</code>.</p> + +<pre class="brush: bash">mkdir my-addon +cd my-addon +jpm init</pre> + +<p>You'll then be asked to supply some information about your add-on: this will be used to create your add-on's <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json">package.json</a> file.</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#title">title</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#name">name</a>: this defaults to the name of the directory in which you are running <code>jpm init</code>. Unless an <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#id"><code>id</code></a> field is present in package.json, jpm will prepend "@" to <code>name</code> and use the result as the <a href="https://developer.mozilla.org/en-US/Add-ons/Install_Manifests#id"><code>id</code> field in the add-on's install manifest</a>.</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#version">version</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#description">description</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#main">entry point</a> (which maps to "main" in package.json)</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#author">author</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#engines">engines</a> (supported applications)</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#license">license</a></li> +</ul> + +<p>Most of these fields have a default, which is shown in brackets after the question. If you just press Enter, your add-on will get the default value.</p> + +<p>Once you've supplied a value or accepted the default for these properties, you'll be shown the complete contents of "package.json" and asked to accept it.</p> + +<p>Then jpm will create an skeleton add-on, as a starting point for your own add-on development, with the following file structure:</p> + +<ul class="directory-tree"> + <li>my-addon + <ul> + <li>index.js</li> + <li>package.json</li> + <li>test + <ul> + <li>test-index.js</li> + </ul> + </li> + </ul> + </li> +</ul> + +<h3 id="jpm_run">jpm run</h3> + +<p>This command runs a new instance of Firefox with the add-on installed:</p> + +<pre class="brush: bash">jpm run</pre> + +<p><code>jpm run</code> accepts the following options:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td style="width: 30%;"><code>-b --binary BINARY</code></td> + <td> + <p>Use the version of Firefox specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.</p> + + <pre class="brush: bash"> +jpm run -b /path/to/Firefox/Nightly</pre> + See <a href="/en-US/Add-ons/SDK/Tools/jpm#Selecting_a_browser_version">Selecting a browser version</a>.</td> + </tr> + <tr> + <td><code>--binary-args CMDARGS</code></td> + <td> + <p>Pass <a href="/en-US/docs/Mozilla/Command_Line_Options">extra arguments</a> to Firefox.</p> + + <p>For example, to pass the <code>-jsconsole</code> argument to Firefox, which will launch the <a href="/en-US/docs/Tools/Browser_Console">Browser Console</a>, try the following:</p> + + <pre class="brush: bash"> +jpm run --binary-args -jsconsole</pre> + + <p>To pass multiple arguments, or arguments containing spaces, quote them:</p> + + <pre class="brush: bash"> +jpm run --binary-args '-url mzl.la -jsconsole'</pre> + </td> + </tr> + <tr> + <td><code>--debug</code></td> + <td>Run the <a href="/en-US/Add-ons/Add-on_Debugger">add-on debugger</a> attached to the add-on.</td> + </tr> + <tr> + <td><code>-o --overload PATH</code></td> + <td> + <p>Rather than use the SDK modules built into Firefox, use the modules found at PATH. If <code>-o</code> is specified and PATH is omitted, jpm will look for the JETPACK_ROOT environment variable and use its value as the path.</p> + + <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Overloading_the_built-in_modules">Overloading the built-in modules</a> for more information.</p> + </td> + </tr> + <tr> + <td><code>-p --profile=<code> PROFILE</code></code></td> + <td> + <p>By default, jpm uses a clean temporary Firefox <a href="http://support.mozilla.com/en-US/kb/profiles">profile</a> each time you call jpm run. Use the <code>--profile</code> option to instruct jpm to launch Firefox with an existing profile.</p> + + <p>The PROFILE value may be a profile name or the path to the profile.</p> + + <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Using_profiles">Using profiles</a> for more information.</p> + </td> + </tr> + <tr> + <td><code>-v --verbose</code></td> + <td>Verbose operation.</td> + </tr> + <tr> + <td><code>--no-copy</code></td> + <td> + <div class="warning">Use with caution because <code>jpm run|test</code> changes many preferences, never use with your main profile.</div> + + <div class="note">This only applies when <code>--profile</code> is used.</div> + Disables the copying of the profile used, which allows one to reuse a profile.</td> + <td> </td> + </tr> + </tbody> +</table> + +<h3 id="jpm_test">jpm test</h3> + +<p>Use this command to run an add-on's unit tests. It will:</p> + +<ul> + <li>look for a directory called "test" under the add-on's root</li> + <li>open every file in there whose name starts with "test-" (note the hyphen after "test" in the filename. <code>jpm test</code> will include a file called "test-myCode.js", but will exclude files called "test_myCode.js" or "testMyCode.js")</li> + <li>call every function exported from that file whose name starts with "test"</li> +</ul> + +<pre class="brush: bash">jpm test +</pre> + +<p>See the <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Unit_testing">tutorial on unit testing</a> and the <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/test_assert">reference documentation for the <code>assert</code> module</a> for more details on this.</p> + +<p><code>jpm test</code> accepts the following options:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td><code>-b --binary BINARY</code></td> + <td> + <p>Use the version of Firefox specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.</p> + + <pre class="brush: bash"> +jpm test -b /path/to/Firefox/Nightly</pre> + + <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Selecting_a_browser_version">Selecting a browser version</a>.</p> + </td> + </tr> + <tr> + <td><code>--binary-args CMDARGS</code></td> + <td> + <p>Pass <a href="http://kb.mozillazine.org/Command_line_arguments">extra arguments</a> to Firefox.</p> + + <p>For example, to pass the <code>-jsconsole</code> argument to Firefox, which will launch the <a href="/en-US/docs/Tools/Browser_Console">Browser Console</a>, try the following:</p> + + <pre class="brush: bash"> +jpm test --binary-args -jsconsole</pre> + + <p>To pass multiple arguments, or arguments containing spaces, quote them:</p> + + <pre class="brush: bash"> +jpm test --binary-args '-url mzl.la -jsconsole'</pre> + </td> + </tr> + <tr> + <td><code>--debug</code></td> + <td>Run the <a href="/en-US/Add-ons/Add-on_Debugger">add-on debugger</a> attached to the add-on.</td> + </tr> + <tr> + <td style="width: 30%;"><code>-f --filter FILE[:TEST]</code></td> + <td> + <p>Only run tests whose filenames match FILE and optionally match TEST, both regexps.</p> + + <pre class="brush: bash"> +jpm test --filter base64:btoa</pre> + + <p>The above command only runs tests in files whose names contain "base64", and in those files only runs tests whose names contain "btoa".</p> + </td> + </tr> + <tr> + <td style="width: 30%;"><code>-o --overload PATH</code></td> + <td> + <p>Rather than use the SDK modules built into Firefox, use the modules found at PATH. If <code>-o</code> is specified and PATH is omitted, jpm will look for the JETPACK_ROOT environment variable and use its value as the path.</p> + + <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Overloading_the_built-in_modules">Overloading the built-in modules</a> for more information.</p> + </td> + </tr> + <tr> + <td style="width: 30%;"><code>-p --profile<code> PROFILE</code></code></td> + <td> + <p>By default, jpm uses a clean temporary Firefox <a href="http://support.mozilla.com/en-US/kb/profiles">profile</a> each time you call jpm run. Use the <code>--profile</code> option to instruct jpm to launch Firefox with an existing profile.</p> + + <p>The PROFILE value may be a profile name or the path to the profile.</p> + + <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Using_profiles">Using profiles</a> for more information.</p> + </td> + </tr> + <tr> + <td><code>--stop-on-error</code></td> + <td> + <p>By default jpm test keeps running tests even after tests fail. Specify <code>--stop-on-error</code> to stop running tests after the first failure:</p> + + <pre class="brush: bash"> +jpm test --stop-on-error</pre> + </td> + </tr> + <tr> + <td><code>--tbpl</code></td> + <td>Print test output in <a href="https://treeherder.mozilla.org/">Treeherder</a> format</td> + </tr> + <tr> + <td><code>--times NUMBER</code></td> + <td> + <p>Run tests NUMBER of times:</p> + + <pre class="brush: bash"> +jpm test --times 2</pre> + </td> + </tr> + <tr> + <td><code>-v --verbose</code></td> + <td>Verbose operation.</td> + </tr> + <tr> + <td><code>--no-copy</code></td> + <td> + <div class="warning">Use with caution because <code>jpm run|test</code> changes many preferences, never use with your main profile.</div> + + <div class="note">This only applies when <code>--profile</code> is used.</div> + Disables the copying of the profile used, which allows one to reuse a profile.</td> + </tr> + </tbody> +</table> + +<h3 id="jpm_xpi">jpm xpi</h3> + +<p>This command packages the add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file, which is the install file format for Mozilla add-ons.</p> + +<pre class="brush: bash">jpm xpi</pre> + +<p>It looks for a file called <code>package.json</code> in the current directory and creates the corresponding XPI file. It ignores any ZIPs or XPIs in the add-on's root, and any test files. It includes all other files. If you want to exclude extra files, see <a href="en-US/Add-ons/SDK/Tools/jpmignore">the .jpmignore file</a>.</p> + +<p>Once you have built an XPI file you can distribute your add-on by submitting it to <a href="http://addons.mozilla.org">addons.mozilla.org</a>.</p> + +<p><code>jpm xpi</code> accepts the following option:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td><code>-v --verbose</code></td> + <td> + <p>Verbose operation:</p> + + <pre class="brush: bash"> +jpm xpi -v</pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="jpm_post">jpm post</h3> + +<p>This command packages the add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file then posts it to some url.</p> + +<pre class="brush: bash">jpm post</pre> + +<p>It looks for a file called <code>package.json</code> in the current directory and creates a XPI file with which to post to the <code>--post-url</code>.</p> + +<p><code>jpm post</code> accepts the following options:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td><code>--post-url URL</code></td> + <td> + <p>The url to post the extension to after creating a XPI.</p> + + <pre class="brush: bash"> +jpm post --post-url http://localhost:8888/</pre> + + <p>See <a href="https://www.npmjs.com/package/jpm#using-post-and-watchpost">Using Post and Watchpost</a> for more information.</p> + </td> + </tr> + <tr> + <td><code>-v --verbose</code></td> + <td> + <p>Verbose operation:</p> + + <pre class="brush: bash"> +jpm post --post-url http://localhost:8888/ -v</pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="jpm_watchpost">jpm watchpost</h3> + +<p>This command packages the add-on as an <a href="https://developer.mozilla.org/en/XPI">XPI</a> file then posts it to some url whenever a file in the current working directory changes.</p> + +<pre class="brush: bash">jpm watchpost</pre> + +<p>Creates a XPI whenever a file in the current working directory changes and posts that to the <code>--post-url</code>.</p> + +<p><code>jpm watchpost</code> accepts the following options:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td><code>--post-url URL</code></td> + <td> + <p>The url to post the extension to after creating a XPI.</p> + + <pre class="brush: bash"> +jpm watchpost --post-url http://localhost:8888/</pre> + + <p>See <a href="https://www.npmjs.com/package/jpm#using-post-and-watchpost">Using Post and Watchpost</a> for more information.</p> + </td> + </tr> + <tr> + <td><code>-v --verbose</code></td> + <td> + <p>Verbose operation:</p> + + <pre class="brush: bash"> +jpm watchpost --post-url http://localhost:8888/ -v</pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="jpm_sign">jpm sign</h3> + +<div class="note"> +<p>This feature is only supported from jpm 1.0.4 onwards.</p> +</div> + +<p>This command retrieves a new <a href="/en-US/docs/XPI">XPI</a> for your add-on signed by Mozilla. This allows you to <a href="/en-US/Add-ons/SDK/Tools/jpm#Supporting_updates_for_self-hosted_add-ons">self-host your add-on</a> so that users can install it without error when <a href="https://wiki.mozilla.org/Add-ons/Extension_Signing">signed add-ons are required</a>.</p> + +<pre class="brush: bash">jpm sign --api-key ${AMO_API_KEY} --api-secret ${AMO_API_SECRET}</pre> + +<p>This creates an <a href="/en-US/docs/XPI">XPI</a>, submits it to the <a href="https://addons.mozilla.org/">addons.mozilla.org</a> <a href="http://olympia.readthedocs.org/en/latest/topics/api/signing.html">signing API</a>, then downloads a new signed <a href="/en-US/docs/XPI">XPI</a> to the working directory if it passes validation. Here are some possible outcomes of running the sign command:</p> + +<ul> + <li>Your add-on passed validation, was signed by Mozilla, and a new signed <a href="/en-US/docs/XPI">XPI</a> was downloaded to your working directory.</li> + <li>Your add-on failed validation, was not signed, and you got a link to a detailed report. After fixing the validation errors, you can run the command again.</li> + <li>Your add-on at this exact version number already exists so it was not signed. You will need to increment the version number in your <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> file and run the command again.</li> +</ul> + +<p>Under the hood, <code>jpm sign</code> creates an unlisted add-on inside <a href="https://addons.mozilla.org/">addons.mozilla.org</a> which means you must distribute the XPI file yourself in order for your users to install it. If you need to create a listed add-on, just <a href="https://addons.mozilla.org/en-US/developers/addon/submit/2">submit it directly to addons.mozilla.org</a> where it will be signed automatically. See the <a href="/en-US/docs/Extension_Versioning%2C_Update_and_Compatibility#Debugging_and_solving_problems">debugging</a> section if you're experiencing difficulty installing a signed add-on.</p> + +<p><code>jpm sign</code> accepts the following options:</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <td><code>--api-key API_KEY</code></td> + <td> + <p>API access key (string) generated on the <a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org key management page</a>.</p> + </td> + </tr> + <tr> + <td><code>--api-secret API_SECRET</code></td> + <td> + <p>API access secret (string) generated on the <a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org key management page</a>. This value should be guarded with care and never checked into version control. If your secret is compromised, another developer could upload add-ons to your account. You should revoke and regenerate compromised API credentials immediately.</p> + </td> + </tr> + <tr> + <td><code>--api-url-prefix http://.../api</code></td> + <td> + <p>An optional API URL prefix in case you'd like to use a pre-production signing API. Here is an example of using a dev instance of <a href="https://addons.mozilla.org/">addons.mozilla.org</a> :</p> + + <pre class="brush: bash"> +jpm sign ... --api-url-prefix https://addons-dev.allizom.org/api/v3</pre> + </td> + </tr> + </tbody> +</table> + +<h2 id="Techniques">Techniques</h2> + +<h3 id="Selecting_a_browser_version">Selecting a browser version</h3> + +<p>By default, <code>jpm run</code> and <code>jpm test</code> will run the release version of Firefox. You can instruct jpm to use a different version in one of two ways:</p> + +<ul> + <li> + <p>you can use the <code>-b</code> or <code>--binary</code> option to instruct jpm to run a different version of Firefox. You can supply a path to a specific binary:</p> + + <pre class="brush: bash">jpm run -b /path/to/Firefox/Nightly</pre> + + <p>As a shorthand for this, you can pass "nightly", "aurora", "beta", or "firefox" and jpm will look in the default location for these Firefox versions:</p> + + <pre class="brush: bash">jpm run -b nightly</pre> + </li> + <li> + <p>you can set the <code>JPM_FIREFOX_BINARY</code> environment variable with the path to the version of Firefox you want to run. When you invoke <code>jpm run</code> or <code>jpm test</code> without the <code>-b</code> option, jpm will first check <code>JPM_FIREFOX_BINARY</code>, and use this as the path if it is set.</p> + </li> +</ul> + +<h3 id="Using_.jpmignore_to_ignore_files">Using <code>.jpmignore</code> to ignore files</h3> + +<p>Using <code>.jpmignore</code> is similar to using <code>.gitignore</code> with <code>git</code>, <code>.hgignore</code> with Mercurial, or <code>.npmignore</code> with <code>npm</code>. By using this file you can let <code>jpm</code> know which files you would like it to ignore when building a <code>.xpi</code> file with <code>jpm xpi</code>.</p> + +<p>Here is an example:</p> + +<pre class="brush: bash"># Ignore .DS_Store files created by mac +.DS_Store + +# Ignore any zip or xpi files +*.zip +*.xpi +</pre> + +<p>A <code>.jpmignore</code> file with the above contents would ignore all zip files and <code>.DS_Store</code> files from the xpi generated by <code>jpm xpi</code>.</p> + +<h3 id="Using_profiles_2"><a name="Using_profiles">Using profiles</a></h3> + +<p>By default, <code>jpm run</code> uses a new profile each time it is executed. This means that any profile-specific data entered from one run of <code>jpm</code> will not, by default, be available in the next run.</p> + +<p>This includes, for example, any extra add-ons you installed, or your history, or any data stored using the <a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-storage">simple-storage</a> API.</p> + +<p>To make <code>jpm</code> use a specific profile, pass the <code>--profile</code> option, specifying the name of the profile you wish to use, or the path to the profile.</p> + +<pre class="brush: bash">jpm run --profile boogaloo +</pre> + +<pre class="brush: bash">jpm run --profile path/to/boogaloo</pre> + +<p>If you supply <code>--profile</code> but its argument is not the name of or path to an existing profile, jpm will open the <a href="https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles">profile manager</a>, enabling you to select and existing profile or create a new one:</p> + +<pre class="brush: bash">jpm run --profile i-dont-exist</pre> + +<h3 id="Developing_without_browser_restarts">Developing without browser restarts</h3> + +<p>Because <code>jpm run</code> restarts the browser each time you invoke it, it can be a little cumbersome if you are making very frequent changes to an add-on. An alternative development model is to use the <a href="https://addons.mozilla.org/en-US/firefox/addon/autoinstaller/" rel="noreferrer">Extension Auto-Installer</a> add-on: this listens for new XPI files on a specified port and installs them automatically. That way you can test new changes without needing to restart the browser:</p> + +<ul> + <li>make a change to your add-on</li> + <li>run <code>jpm post --post-url http://localhost:8888/</code>, to make a xpi and post it.</li> +</ul> + +<p>You could even automate this workflow with a simple script. For example:</p> + +<pre class="brush: bash">jpm watchpost --post-url http://localhost:8888/ +</pre> + +<p>Note that the logging level defined for the console is different when you use this method, compared to the logging level used when an add-on is run using <code>jpm run</code>. This means that if you want to see output from <a href="/en-US/Add-ons/SDK/Tutorials/Logging" rel="noreferrer"><code>console.log()</code></a> messages, you'll have to tweak a setting. See the documentation on <a href="/en-US/Add-ons/SDK/Tools/console#Logging_Levels" rel="noreferrer">logging levels</a> for the details on this.</p> + +<h3 id="Overloading_the_built-in_modules">Overloading the built-in modules</h3> + +<p>The SDK modules you use to implement your add-on are built into Firefox. When you run or package an add-on using <code>jpm run</code> or <code>jpm xpi</code>, the add-on will use the versions of the modules in the version of Firefox that hosts it.</p> + +<p>As an add-on developer, this is usually what you want. But if you're developing the SDK modules themselves, of course, it isn't. In this case you need to:</p> + +<ul> + <li>get a local copy of the SDK modules that you want: this usually means checking out the SDK from its <a href="https://github.com/mozilla/addon-sdk" rel="noreferrer">GitHub repo</a></li> + <li>set the <code>JETPACK_ROOT</code> environment variable to your local copy</li> + <li>pass the <code>-o</code> option to <code>jpm run</code> or <code>jpm xpi</code>:</li> +</ul> + +<pre>jpm run -o +</pre> + +<p>This instructs jpm to use the local copies of the SDK modules, not the ones in Firefox. If you don't want to set the <code>JETPACK_ROOT</code> environment variable, you can pass the location of your copy of the SDK modules along with <code>-o</code>:</p> + +<pre>jpm run -o "/path/to/SDK/"</pre> + +<h3 id="Supporting_updates_for_self-hosted_add-ons">Supporting updates for self-hosted add-ons</h3> + +<div class="note"> +<p>This feature is only supported from jpm 1.0.3 onwards.</p> +</div> + +<p>When you make updates to your add-on to add features or fix bugs, you'll want any previously installed versions of the add-on to update themselves to the new version.</p> + +<p>If you list your add-on on <a href="https://addons.mozilla.org/">addons.mozilla.org</a>, then all you have to do here is submit the new version; add-ons default to checking <a href="https://addons.mozilla.org/">addons.mozilla.org</a> for new versions of themselves. You can stop reading this section.</p> + +<p>If you do not list your add-on on <a href="https://addons.mozilla.org/">addons.mozilla.org</a>, you need to generate a Mozilla-signed XPI and tell Firefox where it can find new versions of your add-on. The way this works is:</p> + +<ul> + <li>you run <a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_sign">jpm sign</a> anytime you need to create a new version</li> + <li>you host the signed add-on XPI and update it when you need to</li> + <li>you host an "update manifest", which, among other things, contains a URL pointing to the XPI</li> + <li>your add-on tells Firefox where it can find the update manifest</li> +</ul> + +<p>To do this, include two extra keys in package.json:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/SDK/Tools/package_json#updateURL">updateURL</a></code>: this is a URL which will be included in the built XPI file (technically, it's in the <a href="/en-US/docs/Mozilla/Add-ons/Install_Manifests">install manifest</a> which <code>jpm xpi</code> builds). It points to your update manifest. The <code>updateURL</code> value <em>may</em> be HTTPS. If it isn't, then you'll also need to sign the update manifest, and then include the public key using the <code><a href="/en-US/Add-ons/SDK/Tools/package_json#updateKey">updateKey</a></code> field in package.json. See <a href="/en-US/docs/Extension_Versioning%2C_Update_and_Compatibility#Securing_Updates">Securing updates</a> for more on this.</li> + <li><code><a href="/en-US/Add-ons/SDK/Tools/package_json#updateLink">updateLink</a></code>: this is the URL which will be included in the update manifest file. It points to the XPI, and <em>must</em> be an HTTPS URL.</li> +</ul> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11847/addons-update.svg" style="" title="[https://mdn.mozillademos.org]"></p> + +<p>If you include <code>updateURL</code> and <code>updateLink</code> (and also <code>updateKey</code> in case <code>updateURL</code> is not HTTPS), then <code>jpm xpi</code> will:</p> + +<ul> + <li>embed the value you supplied for <code>updateURL</code> in the XPI it generates</li> + <li>generate an update manifest alongside the XPI, and embed the value you supplied for <code>updateLink</code> in the manifest</li> +</ul> + +<p>You then host the update manifest at <code>updateURL</code>, and host new versions of the XPI at <code>updateLink</code>.</p> + +<p>For some more details on this, see <a href="/en-US/docs/Extension_Versioning,_Update_and_Compatibility#Automatic_Add-on_Update_Checking">Automatic Add-on Update Checking</a>.</p> |