You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ja...@apache.org on 2019/05/10 10:26:40 UTC
svn commit: r1859075 - in /cordova/site/public:
docs/en/9.x/platform_plugin_versioning_ref/index.html
docs/en/dev/platform_plugin_versioning_ref/index.html feed.xml
Author: janpio
Date: Fri May 10 10:26:40 2019
New Revision: 1859075
URL: http://svn.apache.org/viewvc?rev=1859075&view=rev
Log:
Updated docs
Modified:
cordova/site/public/docs/en/9.x/platform_plugin_versioning_ref/index.html
cordova/site/public/docs/en/dev/platform_plugin_versioning_ref/index.html
cordova/site/public/feed.xml
Modified: cordova/site/public/docs/en/9.x/platform_plugin_versioning_ref/index.html
URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/9.x/platform_plugin_versioning_ref/index.html?rev=1859075&r1=1859074&r2=1859075&view=diff
==============================================================================
--- cordova/site/public/docs/en/9.x/platform_plugin_versioning_ref/index.html (original)
+++ cordova/site/public/docs/en/9.x/platform_plugin_versioning_ref/index.html Fri May 10 10:26:40 2019
@@ -2516,182 +2516,276 @@
<div id="page-toc-source">
<h1>Platforms and Plugins Version Management</h1>
-<p>From version 4.3.0 onwards, Cordova provides the ability to save and restore platforms and plugins.</p>
+<p>Cordova provides the ability to save and restore platforms and plugins.</p>
<p>This feature allows developers to save and restore their app to a known state without having to check in all of the platform and plugin source code.</p>
-<p>When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved in config.xml and package.json. It is possible to add a platform or plugin by editing package.json or config.xml directly, assuming you know the right tags + syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the command line cordova commands <code>cordova plugin add|remove ...</code> and <code>cordova platform add|remove ...</code> to avoid any out of sync issues.</p>
+<p>When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved to the <code>package.json</code> file. It is also possible to add a platform or plugin by editing the <code>package.json</code> file directly, assuming you know the right tags and syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the Cordova CLI commands <code>cordova plugin add|remove ...</code> and <code>cordova platform add|remove ...</code> to avoid any out of sync issues.</p>
-<p>The 'restore' step happens automatically when a <strong>'cordova prepare'</strong> is issued, making use of information previously saved in the config.xml and package.json files.</p>
+<p>The <strong>restore</strong> step happens automatically when a <strong><code>cordova prepare</code></strong> is issued, making use of information previously saved in the <code>package.json</code> and <code>config.xml</code> files.</p>
<p>One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository.</p>
<h2>Platform Versioning</h2>
-<h3>Saving platforms</h3>
+<h3>Saving Platforms</h3>
-<p>To save a platform, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform add <platform[@<version>] | directory | git_url>
+<p>To save a platform, issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform add <platform[@<version>] | directory | git_url>
</code></pre></div>
-<p>After running the above command, the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
- ...
- <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"~4.0.0"</span> <span class="nt">/></span>
- ...
-<span class="nt"></xml></span>
+<p>After running the above command, the <strong><code>package.json</code></strong> should contain something as seen below:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"platforms"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"android"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-android"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^8.0.0"</span><span class="p">,</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>The <code>--nosave</code> flag prevents adding and deleting specified platforms to the <code>package.json</code> file. To prevent saving a platform, issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform add <platform[@<version>] | directory | git_url> <span class="nt">--nosave</span>
</code></pre></div>
-<p>After running the above command, the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"^4.0.0"</span><span class="o">}</span>
+<p>Some Examples:</p>
+
+<ul>
+<li><strong><code>cordova platform add android</code></strong> </li>
+</ul>
+
+<p>Retrieves the pinned version of <code>cordova-android</code> platform from npm, adds it to the project and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add android@7.1.4</code></strong></li>
+</ul>
+
+<p>Retrieves the <code>cordova-android</code> platform version <code>7.1.4</code> from npm, adds it to the project and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add https://github.com/apache/cordova-android.git</code></strong></li>
+</ul>
+
+<p><strong><code>cordova platform add https://github.com/apache/cordova-android</code></strong></p>
+
+<p><strong><code>cordova platform add github:apache/cordova-android</code></strong></p>
+
+<p>npm retrieves the <code>cordova-android</code> platform from the git repository, adds it to the project and updates the <code>package.json</code>.</p>
+
+<ul>
+<li><strong><code>cordova platform add C:/path/to/android/platform</code></strong></li>
+</ul>
+
+<p>Retrieves the Android platform from the specified directory, adds it to the project, and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add android --nosave</code></strong></li>
+</ul>
+
+<p>Retrieves the pinned version of <code>cordova-android</code> platform from npm, adds it to the project, but does not add it to the <code>package.json</code> file.</p>
+
+<h3>Updating or Removing Platforms</h3>
+
+<p>It is possible to update and delete a platform from <code>config.xml</code> and <code>package.json</code>.</p>
+
+<p>To update a platform, execute the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform update <platform[@<version>] | directory | git_url>
</code></pre></div>
-<p>The '--nosave' flag prevents adding and deleting specified platforms from config.xml and package.json. To prevent saving a platform, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform add <platform[@<version>] | directory | git_url> <span class="nt">--nosave</span>
+<p>To remove a platform, execute one of the following commands:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform remove <platform>
+cordova platform rm <platform>
</code></pre></div>
-<p>Some examples :</p>
+<p>Some Examples:</p>
<ul>
-<li><strong>'cordova platform add android'</strong> => retrieves the pinned version of the android platform, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova platform add android@3.7.0'</strong> => retrieves the android platform, version 3.7.0 from npm, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova platform add https://github.com/apache/cordova-android.git'</strong> => npm installs the specified cordova-android from the git repository, adds the android platform to the project, then updates config.xml and package.json and points its version to the specified git-url.</li>
-<li><strong>'cordova platform add C:/path/to/android/platform'</strong> => retrieves the android platform from the specified directory, adds it to the project, then updates config.xml and package.json and points to the directory.</li>
-<li><strong>'cordova platform add android --nosave'</strong> => retrieves the pinned version of the android platform, adds it to the project, but does not add it to config.xml or package.json.</li>
-<li><strong>'cordova platform remove android --nosave'</strong> => removes the android platform from the project, but does not remove it from config.xml or package.json.<br></li>
+<li><strong><code>cordova platform update android</code></strong></li>
</ul>
-<h3>Mass saving platforms on an existing project</h3>
+<p>In addition to updating the <code>cordova-android</code> platform to the pinned version, it updates the <code>package.json</code> file.</p>
-<p>If you have a pre-existing project and you want to save all the currently added platforms in your project, you can use :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform save
-</code></pre></div>
-<h3>Updating / Removing platforms</h3>
+<ul>
+<li><strong><code>cordova platform update android@3.8.0</code></strong></li>
+</ul>
-<p>It is also possible to update/delete from config.xml and package.json during the commands 'cordova platform update' and 'cordova platform remove' :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform update <platform[@<version>] | directory | git_url> <span class="nt">--save</span>
-<span class="nv">$ </span>cordova platform remove <platform>
-</code></pre></div>
-<p>Some examples :</p>
+<p>In addition to updating the <code>cordova-android</code> platform to version <code>3.8.0</code> it updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform update /path/to/android/platform</code></strong></li>
+</ul>
+
+<p>In addition to updating the <code>cordova-android</code> platform to version found in the provided folder, it updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform remove android</code></strong></li>
+</ul>
+
+<p>Removes the <code>cordova-android</code> platform from the project and removes it from the <code>package.json</code> file.</p>
+
+<p><em>Note: If the platform definition existed in <code>config.xml</code> from a previous version of Cordova CLI, it will also be removed from <code>config.xml</code>.</em></p>
<ul>
-<li><strong>'cordova platform update android --save'</strong> => In addition to updating the android platform to the pinned version, update config.xml entry</li>
-<li><strong>'cordova platform update android@3.8.0 --save'</strong> => In addition to updating the android platform to version 3.8.0, update config.xml entry</li>
-<li><strong>'cordova platform update /path/to/android/platform --save'</strong> => In addition to updating the android platform to version in the folder, update config.xml entry</li>
-<li><strong>'cordova platform remove android'</strong> => Removes the android platform from the project and deletes its entry from config.xml and package.json.</li>
+<li><strong><code>cordova platform remove android --nosave</code></strong></li>
</ul>
-<h3>Restoring platforms</h3>
+<p>Removes the <code>cordova-android</code> platform from the project, but does not remove it from the <code>package.json</code> file.</p>
+
+<h3>Restoring Platforms</h3>
+
+<p>Platforms are automatically restored from the <code>package.json</code> (and <code>config.xml</code>) when executing the <strong><code>cordova prepare</code></strong> command.</p>
+
+<p>If a platform is defined in both files, the information defined in <code>package.json</code> is used as the source of truth.</p>
-<p>Platforms are automatically restored from package.json and config.xml when the <strong>'cordova prepare'</strong> command is run. After prepare is run, package.json and config.xml should contain identical platforms and versions.</p>
+<p>After <code>prepare</code>, any platforms restored from <code>config.xml</code> will update the <code>package.json</code> file to reflect the values taken from <code>config.xml</code>.</p>
-<p>If you add a platform without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, <strong>if found</strong>. In case of conflicts, package.json is given precedence over config.xml.</p>
+<p>If you add a platform without specifying a <code><version | folder | git_url></code>, the version that will be installed is taken from <code>package.json</code> or <code>config.xml</code>.</p>
+
+<p><strong>If discovered</strong> in both files, <code>package.json</code> is given higher priority over <code>config.xml</code>.</p>
<p>Example:</p>
-<p>Suppose your config.xml file contains the following entry:</p>
+<p>Suppose your <code>config.xml</code> file contains the following entry:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
...
- <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"3.7.0"</span> <span class="nt">/></span>
+ <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"7.1.4"</span> <span class="nt">/></span>
...
<span class="nt"></xml></span>
</code></pre></div>
-<p>If you run the command <strong>'cordova platform add android'</strong> (no version/folder/git_url specified), the platform 'android@3.7.0' (as retrieved from config.xml) will be installed.</p>
+<p>If you run the command <strong><code>cordova platform add android</code></strong> with no <code><version | folder | git_url></code> specified, the platform <code>android@7.1.4</code> will be retrieved and installed.</p>
-<p><strong>Example for order of precedence for restoring platforms:</strong></p>
+<p><strong>Example Order of Priority for Restoring Platforms:</strong></p>
-<p>Suppose your config.xml has this platform and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><engine <span class="nv">name</span><span class="o">=</span><span class="s2">"android"</span> <span class="nv">spec</span><span class="o">=</span>â1.0.0â />
-</code></pre></div>
-<p>Suppose your package.json has this platform and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"4.0.0"</span><span class="o">}</span>
-</code></pre></div>
-<p>When prepare is run, package.jsonâs contents are giving precedence and both config.xml and package.json are updated so that they have identical platforms and variables. Notice how package.json's version (4.0.0) has <strong>replaced</strong> config.xml's version (1.0.0).</p>
+<p>Suppose you have defined in <code>config.xml</code> and <code>package.json</code> a platform and version as follows:</p>
-<p>After running <strong>'cordova prepare'</strong> , the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><engine <span class="nv">name</span><span class="o">=</span><span class="s2">"android"</span> <span class="nv">spec</span><span class="o">=</span>â4.0.0â />
-</code></pre></div>
-<p>After running <strong>'cordova prepare'</strong> , the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span>,]<span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"4.0.0"</span><span class="o">}</span>
+<p><strong><code>config.xml</code></strong>:</p>
+<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">â7.4.1â</span> <span class="nt">/></span>
</code></pre></div>
+<p><strong><code>package.json</code></strong>:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"platforms"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"android"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-android"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^8.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>When <code>prepare</code> is executed, the version from <code>package.json</code> has higher priority over <code>config.xml</code> and version <code>^8.0.0</code> will be installed.</p>
+
<hr>
<h2>Plugin Versioning</h2>
-<p><em>(The plugin commands are a mirror of the platform commands)</em></p>
+<p>The plugin commands are a mirror of the platform commands:</p>
-<h3>Saving plugins</h3>
+<h3>Saving Plugins</h3>
-<p>To save a plugin, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin add <plugin[@<version>] | directory | git_url>
+<p>To save a plugin, you issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin add <plugin[@<version>] | directory | git_url>
</code></pre></div>
-<p>After running the above command, the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
- ...
- <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-console"</span> <span class="na">spec=</span><span class="s">"~1.0.0"</span> <span class="nt">/></span>
- ...
-<span class="nt"></xml></span>
-</code></pre></div>
-<p>After running the above command, the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">[</span><span class="s2">"cordova-plugin-console"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-console"</span>: <span class="s2">"^1.0.0"</span><span class="o">}</span>
+<p>After running the above command, the <strong><code>package.json</code></strong> should contain something as seen below:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"plugins"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"cordova-plugin-device"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"devDependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-plugin-device"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^1.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>The <code>--nosave</code> flag prevents adding and deleting specified plugins from <code>package.json</code>. To prevent saving a plugin, you issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin add <plugin[@<version>] | directory | git_url> <span class="nt">--nosave</span>
</code></pre></div>
-<p>The '--nosave' flag prevents adding and deleting specified plugins from config.xml and package.json. To prevent saving a plugin, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin add <plugin[@<version>] | directory | git_url> <span class="nt">--nosave</span>
-</code></pre></div>
-<p>Some examples :</p>
+<p>Some Examples:</p>
+
+<ul>
+<li><strong><code>cordova plugin add cordova-plugin-device</code></strong></li>
+</ul>
+
+<p>Retrieves the pinned version of the <code>cordova-plugin-device</code> plugin from npm, adds it to the project and updates the <code>package.json</code> file.</p>
<ul>
-<li><strong>'cordova plugin add cordova-plugin-console'</strong> => retrieves the pinned version of the console plugin, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova plugin add cordova-plugin-console@0.2.13'</strong> => retrieves the android plugin, version 0.2.13 from npm, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova plugin add https://github.com/apache/cordova-plugin-console.git'</strong> => npm installs specified console plugin from the git repository, adds the console plugin to the project, then updates config.xml and and package.json and points its version to the specified git-url.</li>
-<li><strong>'cordova plugin add C:/path/to/console/plugin'</strong> => retrieves the console plugin from the specified directory, adds it to the project, then updates config.xml and package.json and points to the directory.</li>
+<li><strong><code>cordova plugin add cordova-plugin-device@2.0.1</code></strong></li>
</ul>
-<h3>Mass saving plugins on an existing project</h3>
+<p>Retrieves the <code>cordova-plugin-device</code> plugin at version <code>2.0.1</code> from npm, adds it to the project and updates the <code>package.json</code> file.</p>
-<p>If you have a pre-existing project and you want to save all currently added plugins in the project, you can use :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin save
+<ul>
+<li><strong><code>cordova plugin add https://github.com/apache/cordova-plugin-device.git</code></strong></li>
+</ul>
+
+<p><strong><code>cordova plugin add https://github.com/apache/cordova-plugin-device</code></strong></p>
+
+<p><strong><code>cordova plugin add github:apache/cordova-plugin-device</code></strong></p>
+
+<p>npm retrieves the <code>cordova-plugin-device</code> plugin from the git repository, adds it to the project and updates the <code>package.json</code>.</p>
+
+<ul>
+<li><strong><code>cordova plugin add C:/path/to/console/plugin</code></strong></li>
+</ul>
+
+<p>Retrieves the <code>cordova-plugin-device</code> plugin from the specified directory, adds it to the project, and updates the <code>package.json</code> file.</p>
+
+<h3>Mass Saving of Plugins on an Existing Project</h3>
+
+<p>If you have a pre-existing project and you want to save all currently added plugins in the project, you can use:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin save
</code></pre></div>
-<h3>Removing plugins</h3>
+<h3>Removing Plugins</h3>
-<p>It is also possible to delete from config.xml and package.json during the command 'cordova plugin remove' :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin remove <plugin>
+<p>It is possible to delete a plugin from <code>config.xml</code> and <code>package.json</code> with one of the following commands:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin remove <plugin>
+cordova plugin rm <plugin>
</code></pre></div>
-<p>For example:</p>
+<p>For Example:</p>
<ul>
-<li><strong>'cordova plugin remove cordova-plugin-console'</strong> => Removes the console plugin from the project and deletes its entry from config.xml and package.json.</li>
+<li><strong><code>cordova plugin remove cordova-plugin-device</code></strong></li>
</ul>
-<h3>Restoring plugins</h3>
+<p>Removes the <code>cordova-plugin-device</code> plugin from the project and deletes its entry from <code>package.json</code>.</p>
+
+<p><em>Note: If the plugin definition existed in <code>config.xml</code> from a previous version of Cordova CLI, it will also be removed from <code>config.xml</code>.</em></p>
+
+<h3>Restoring Plugins</h3>
+
+<p>Plugins are automatically restored from <code>package.json</code> and <code>config.xml</code> when executing the <strong><code>cordova prepare</code></strong> command.</p>
+
+<p>If a plugin is defined in both files, the information defined in <code>package.json</code> is used as the source of truth.</p>
-<p>Plugins are automatically restored from package.json and config.xml when the <strong>'cordova prepare'</strong> command is run. After prepare is run, package.json and config.xml should contain identical plugins and versions.</p>
+<p>After <code>prepare</code>, any plugins restored from <code>config.xml</code> will update the <code>package.json</code> file to reflect the values taken from <code>config.xml</code>.</p>
-<p>If you add a plugin without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, <strong>if found</strong>. In case of conflicts, package.json is given precedence over config.xml.</p>
+<p>If you add a plugin without specifying a <code><version | folder | git_url></code>, the version that will be installed is taken from <code>package.json</code> or <code>config.xml</code>.</p>
+
+<p><strong>If discovered</strong> in both files, <code>package.json</code> is given higher priority over <code>config.xml</code>.</p>
<p>Example:</p>
-<p>Suppose your config.xml file contains the following entry:</p>
+<p>Suppose your <code>config.xml</code> file contains the following entry:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
...
- <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-console"</span> <span class="na">spec=</span><span class="s">"0.2.11"</span> <span class="nt">/></span>
+ <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-device"</span> <span class="na">spec=</span><span class="s">"2.0.1"</span> <span class="nt">/></span>
...
<span class="nt"></ xml></span>
</code></pre></div>
-<p>If you run the command <strong>'cordova plugin add cordova-plugin-console'</strong> (no version/folder/git_url specified), the plugin 'cordova-plugin-console@0.2.11' (as retrieved from config.xml) will be installed.</p>
+<p>If you run the command <strong><code>cordova plugin add cordova-plugin-device</code></strong> with no <code><version | folder | git_url></code> specified, the platform <code>cordova-plugin-device@2.0.1</code> will be retrieved and installed.</p>
-<p><strong>Example for order of precedence for restoring plugins:</strong></p>
+<p><strong>Example Order of Priority for Restoring Plugins:</strong></p>
-<p>Supposed your config.xml has this plugin and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><plugin <span class="nv">name</span><span class="o">=</span><span class="s2">"cordova-plugin-splashscreen"</span>/>
-</code></pre></div>
-<p>Suppose your package.json has this plugin and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span> : <span class="o">{}</span> <span class="o">}</span> <span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span>: <span class="s2">"1.0.0"</span><span class="o">}</span>
-</code></pre></div>
-<p>When prepare is run, package.jsonâs contents are giving precedence and both config.xml and package.json are updated so that they have identical plugins and variables. Notice how package.json's version (1.0.0) is now in config.xml.</p>
+<p>Suppose you have defined in <code>config.xml</code> and <code>package.json</code> a plugin and version as follows:</p>
-<p>After running <strong>'cordova prepare'</strong> , the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><plugin <span class="nv">name</span><span class="o">=</span><span class="s2">"cordova-plugin-splashscreen"</span> <span class="nv">spec</span><span class="o">=</span><span class="s2">"1.0.0"</span>/>
-</code></pre></div>
-<p>After running <strong>'cordova prepare'</strong> , the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span> : <span class="o">{}</span> <span class="o">}</span> <span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span>: <span class="s2">"1.0.0"</span><span class="o">}</span>
+<p><strong><code>config.xml</code></strong>:</p>
+<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-splashscreen"</span><span class="nt">/></span>
</code></pre></div>
+<p><strong><code>package.json</code></strong>:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"plugins"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"cordova-plugin-splashscreen"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"devDependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-plugin-splashscreen"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>When <code>prepare</code> is executed, the version from <code>package.json</code> has higher priority over <code>config.xml</code> and version <code>1.0.0</code> will be installed.</p>
+
</div>
</div>
Modified: cordova/site/public/docs/en/dev/platform_plugin_versioning_ref/index.html
URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/dev/platform_plugin_versioning_ref/index.html?rev=1859075&r1=1859074&r2=1859075&view=diff
==============================================================================
--- cordova/site/public/docs/en/dev/platform_plugin_versioning_ref/index.html (original)
+++ cordova/site/public/docs/en/dev/platform_plugin_versioning_ref/index.html Fri May 10 10:26:40 2019
@@ -2524,182 +2524,276 @@
<div id="page-toc-source">
<h1>Platforms and Plugins Version Management</h1>
-<p>From version 4.3.0 onwards, Cordova provides the ability to save and restore platforms and plugins.</p>
+<p>Cordova provides the ability to save and restore platforms and plugins.</p>
<p>This feature allows developers to save and restore their app to a known state without having to check in all of the platform and plugin source code.</p>
-<p>When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved in config.xml and package.json. It is possible to add a platform or plugin by editing package.json or config.xml directly, assuming you know the right tags + syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the command line cordova commands <code>cordova plugin add|remove ...</code> and <code>cordova platform add|remove ...</code> to avoid any out of sync issues.</p>
+<p>When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved to the <code>package.json</code> file. It is also possible to add a platform or plugin by editing the <code>package.json</code> file directly, assuming you know the right tags and syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the Cordova CLI commands <code>cordova plugin add|remove ...</code> and <code>cordova platform add|remove ...</code> to avoid any out of sync issues.</p>
-<p>The 'restore' step happens automatically when a <strong>'cordova prepare'</strong> is issued, making use of information previously saved in the config.xml and package.json files.</p>
+<p>The <strong>restore</strong> step happens automatically when a <strong><code>cordova prepare</code></strong> is issued, making use of information previously saved in the <code>package.json</code> and <code>config.xml</code> files.</p>
<p>One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository.</p>
<h2>Platform Versioning</h2>
-<h3>Saving platforms</h3>
+<h3>Saving Platforms</h3>
-<p>To save a platform, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform add <platform[@<version>] | directory | git_url>
+<p>To save a platform, issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform add <platform[@<version>] | directory | git_url>
</code></pre></div>
-<p>After running the above command, the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
- ...
- <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"~4.0.0"</span> <span class="nt">/></span>
- ...
-<span class="nt"></xml></span>
+<p>After running the above command, the <strong><code>package.json</code></strong> should contain something as seen below:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"platforms"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"android"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-android"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^8.0.0"</span><span class="p">,</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>The <code>--nosave</code> flag prevents adding and deleting specified platforms to the <code>package.json</code> file. To prevent saving a platform, issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform add <platform[@<version>] | directory | git_url> <span class="nt">--nosave</span>
</code></pre></div>
-<p>After running the above command, the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"^4.0.0"</span><span class="o">}</span>
+<p>Some Examples:</p>
+
+<ul>
+<li><strong><code>cordova platform add android</code></strong> </li>
+</ul>
+
+<p>Retrieves the pinned version of <code>cordova-android</code> platform from npm, adds it to the project and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add android@7.1.4</code></strong></li>
+</ul>
+
+<p>Retrieves the <code>cordova-android</code> platform version <code>7.1.4</code> from npm, adds it to the project and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add https://github.com/apache/cordova-android.git</code></strong></li>
+</ul>
+
+<p><strong><code>cordova platform add https://github.com/apache/cordova-android</code></strong></p>
+
+<p><strong><code>cordova platform add github:apache/cordova-android</code></strong></p>
+
+<p>npm retrieves the <code>cordova-android</code> platform from the git repository, adds it to the project and updates the <code>package.json</code>.</p>
+
+<ul>
+<li><strong><code>cordova platform add C:/path/to/android/platform</code></strong></li>
+</ul>
+
+<p>Retrieves the Android platform from the specified directory, adds it to the project, and updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform add android --nosave</code></strong></li>
+</ul>
+
+<p>Retrieves the pinned version of <code>cordova-android</code> platform from npm, adds it to the project, but does not add it to the <code>package.json</code> file.</p>
+
+<h3>Updating or Removing Platforms</h3>
+
+<p>It is possible to update and delete a platform from <code>config.xml</code> and <code>package.json</code>.</p>
+
+<p>To update a platform, execute the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform update <platform[@<version>] | directory | git_url>
</code></pre></div>
-<p>The '--nosave' flag prevents adding and deleting specified platforms from config.xml and package.json. To prevent saving a platform, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform add <platform[@<version>] | directory | git_url> <span class="nt">--nosave</span>
+<p>To remove a platform, execute one of the following commands:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova platform remove <platform>
+cordova platform rm <platform>
</code></pre></div>
-<p>Some examples :</p>
+<p>Some Examples:</p>
<ul>
-<li><strong>'cordova platform add android'</strong> => retrieves the pinned version of the android platform, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova platform add android@3.7.0'</strong> => retrieves the android platform, version 3.7.0 from npm, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova platform add https://github.com/apache/cordova-android.git'</strong> => npm installs the specified cordova-android from the git repository, adds the android platform to the project, then updates config.xml and package.json and points its version to the specified git-url.</li>
-<li><strong>'cordova platform add C:/path/to/android/platform'</strong> => retrieves the android platform from the specified directory, adds it to the project, then updates config.xml and package.json and points to the directory.</li>
-<li><strong>'cordova platform add android --nosave'</strong> => retrieves the pinned version of the android platform, adds it to the project, but does not add it to config.xml or package.json.</li>
-<li><strong>'cordova platform remove android --nosave'</strong> => removes the android platform from the project, but does not remove it from config.xml or package.json.<br></li>
+<li><strong><code>cordova platform update android</code></strong></li>
</ul>
-<h3>Mass saving platforms on an existing project</h3>
+<p>In addition to updating the <code>cordova-android</code> platform to the pinned version, it updates the <code>package.json</code> file.</p>
-<p>If you have a pre-existing project and you want to save all the currently added platforms in your project, you can use :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform save
-</code></pre></div>
-<h3>Updating / Removing platforms</h3>
+<ul>
+<li><strong><code>cordova platform update android@3.8.0</code></strong></li>
+</ul>
-<p>It is also possible to update/delete from config.xml and package.json during the commands 'cordova platform update' and 'cordova platform remove' :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova platform update <platform[@<version>] | directory | git_url> <span class="nt">--save</span>
-<span class="nv">$ </span>cordova platform remove <platform>
-</code></pre></div>
-<p>Some examples :</p>
+<p>In addition to updating the <code>cordova-android</code> platform to version <code>3.8.0</code> it updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform update /path/to/android/platform</code></strong></li>
+</ul>
+
+<p>In addition to updating the <code>cordova-android</code> platform to version found in the provided folder, it updates the <code>package.json</code> file.</p>
+
+<ul>
+<li><strong><code>cordova platform remove android</code></strong></li>
+</ul>
+
+<p>Removes the <code>cordova-android</code> platform from the project and removes it from the <code>package.json</code> file.</p>
+
+<p><em>Note: If the platform definition existed in <code>config.xml</code> from a previous version of Cordova CLI, it will also be removed from <code>config.xml</code>.</em></p>
<ul>
-<li><strong>'cordova platform update android --save'</strong> => In addition to updating the android platform to the pinned version, update config.xml entry</li>
-<li><strong>'cordova platform update android@3.8.0 --save'</strong> => In addition to updating the android platform to version 3.8.0, update config.xml entry</li>
-<li><strong>'cordova platform update /path/to/android/platform --save'</strong> => In addition to updating the android platform to version in the folder, update config.xml entry</li>
-<li><strong>'cordova platform remove android'</strong> => Removes the android platform from the project and deletes its entry from config.xml and package.json.</li>
+<li><strong><code>cordova platform remove android --nosave</code></strong></li>
</ul>
-<h3>Restoring platforms</h3>
+<p>Removes the <code>cordova-android</code> platform from the project, but does not remove it from the <code>package.json</code> file.</p>
+
+<h3>Restoring Platforms</h3>
+
+<p>Platforms are automatically restored from the <code>package.json</code> (and <code>config.xml</code>) when executing the <strong><code>cordova prepare</code></strong> command.</p>
+
+<p>If a platform is defined in both files, the information defined in <code>package.json</code> is used as the source of truth.</p>
-<p>Platforms are automatically restored from package.json and config.xml when the <strong>'cordova prepare'</strong> command is run. After prepare is run, package.json and config.xml should contain identical platforms and versions.</p>
+<p>After <code>prepare</code>, any platforms restored from <code>config.xml</code> will update the <code>package.json</code> file to reflect the values taken from <code>config.xml</code>.</p>
-<p>If you add a platform without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, <strong>if found</strong>. In case of conflicts, package.json is given precedence over config.xml.</p>
+<p>If you add a platform without specifying a <code><version | folder | git_url></code>, the version that will be installed is taken from <code>package.json</code> or <code>config.xml</code>.</p>
+
+<p><strong>If discovered</strong> in both files, <code>package.json</code> is given higher priority over <code>config.xml</code>.</p>
<p>Example:</p>
-<p>Suppose your config.xml file contains the following entry:</p>
+<p>Suppose your <code>config.xml</code> file contains the following entry:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
...
- <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"3.7.0"</span> <span class="nt">/></span>
+ <span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">"7.1.4"</span> <span class="nt">/></span>
...
<span class="nt"></xml></span>
</code></pre></div>
-<p>If you run the command <strong>'cordova platform add android'</strong> (no version/folder/git_url specified), the platform 'android@3.7.0' (as retrieved from config.xml) will be installed.</p>
+<p>If you run the command <strong><code>cordova platform add android</code></strong> with no <code><version | folder | git_url></code> specified, the platform <code>android@7.1.4</code> will be retrieved and installed.</p>
-<p><strong>Example for order of precedence for restoring platforms:</strong></p>
+<p><strong>Example Order of Priority for Restoring Platforms:</strong></p>
-<p>Suppose your config.xml has this platform and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><engine <span class="nv">name</span><span class="o">=</span><span class="s2">"android"</span> <span class="nv">spec</span><span class="o">=</span>â1.0.0â />
-</code></pre></div>
-<p>Suppose your package.json has this platform and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"4.0.0"</span><span class="o">}</span>
-</code></pre></div>
-<p>When prepare is run, package.jsonâs contents are giving precedence and both config.xml and package.json are updated so that they have identical platforms and variables. Notice how package.json's version (4.0.0) has <strong>replaced</strong> config.xml's version (1.0.0).</p>
+<p>Suppose you have defined in <code>config.xml</code> and <code>package.json</code> a platform and version as follows:</p>
-<p>After running <strong>'cordova prepare'</strong> , the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><engine <span class="nv">name</span><span class="o">=</span><span class="s2">"android"</span> <span class="nv">spec</span><span class="o">=</span>â4.0.0â />
-</code></pre></div>
-<p>After running <strong>'cordova prepare'</strong> , the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"platforms"</span>: <span class="o">[</span><span class="s2">"android"</span>,]<span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-android"</span>: <span class="s2">"4.0.0"</span><span class="o">}</span>
+<p><strong><code>config.xml</code></strong>:</p>
+<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><engine</span> <span class="na">name=</span><span class="s">"android"</span> <span class="na">spec=</span><span class="s">â7.4.1â</span> <span class="nt">/></span>
</code></pre></div>
+<p><strong><code>package.json</code></strong>:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"platforms"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"android"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"dependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-android"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^8.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>When <code>prepare</code> is executed, the version from <code>package.json</code> has higher priority over <code>config.xml</code> and version <code>^8.0.0</code> will be installed.</p>
+
<hr>
<h2>Plugin Versioning</h2>
-<p><em>(The plugin commands are a mirror of the platform commands)</em></p>
+<p>The plugin commands are a mirror of the platform commands:</p>
-<h3>Saving plugins</h3>
+<h3>Saving Plugins</h3>
-<p>To save a plugin, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin add <plugin[@<version>] | directory | git_url>
+<p>To save a plugin, you issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin add <plugin[@<version>] | directory | git_url>
</code></pre></div>
-<p>After running the above command, the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
- ...
- <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-console"</span> <span class="na">spec=</span><span class="s">"~1.0.0"</span> <span class="nt">/></span>
- ...
-<span class="nt"></xml></span>
-</code></pre></div>
-<p>After running the above command, the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">[</span><span class="s2">"cordova-plugin-console"</span><span class="o">]}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-console"</span>: <span class="s2">"^1.0.0"</span><span class="o">}</span>
+<p>After running the above command, the <strong><code>package.json</code></strong> should contain something as seen below:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"plugins"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"cordova-plugin-device"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"devDependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-plugin-device"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^1.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>The <code>--nosave</code> flag prevents adding and deleting specified plugins from <code>package.json</code>. To prevent saving a plugin, you issue the following command:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin add <plugin[@<version>] | directory | git_url> <span class="nt">--nosave</span>
</code></pre></div>
-<p>The '--nosave' flag prevents adding and deleting specified plugins from config.xml and package.json. To prevent saving a plugin, you issue the following command :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin add <plugin[@<version>] | directory | git_url> <span class="nt">--nosave</span>
-</code></pre></div>
-<p>Some examples :</p>
+<p>Some Examples:</p>
+
+<ul>
+<li><strong><code>cordova plugin add cordova-plugin-device</code></strong></li>
+</ul>
+
+<p>Retrieves the pinned version of the <code>cordova-plugin-device</code> plugin from npm, adds it to the project and updates the <code>package.json</code> file.</p>
<ul>
-<li><strong>'cordova plugin add cordova-plugin-console'</strong> => retrieves the pinned version of the console plugin, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova plugin add cordova-plugin-console@0.2.13'</strong> => retrieves the android plugin, version 0.2.13 from npm, adds it to the project and then updates config.xml and package.json.</li>
-<li><strong>'cordova plugin add https://github.com/apache/cordova-plugin-console.git'</strong> => npm installs specified console plugin from the git repository, adds the console plugin to the project, then updates config.xml and and package.json and points its version to the specified git-url.</li>
-<li><strong>'cordova plugin add C:/path/to/console/plugin'</strong> => retrieves the console plugin from the specified directory, adds it to the project, then updates config.xml and package.json and points to the directory.</li>
+<li><strong><code>cordova plugin add cordova-plugin-device@2.0.1</code></strong></li>
</ul>
-<h3>Mass saving plugins on an existing project</h3>
+<p>Retrieves the <code>cordova-plugin-device</code> plugin at version <code>2.0.1</code> from npm, adds it to the project and updates the <code>package.json</code> file.</p>
-<p>If you have a pre-existing project and you want to save all currently added plugins in the project, you can use :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin save
+<ul>
+<li><strong><code>cordova plugin add https://github.com/apache/cordova-plugin-device.git</code></strong></li>
+</ul>
+
+<p><strong><code>cordova plugin add https://github.com/apache/cordova-plugin-device</code></strong></p>
+
+<p><strong><code>cordova plugin add github:apache/cordova-plugin-device</code></strong></p>
+
+<p>npm retrieves the <code>cordova-plugin-device</code> plugin from the git repository, adds it to the project and updates the <code>package.json</code>.</p>
+
+<ul>
+<li><strong><code>cordova plugin add C:/path/to/console/plugin</code></strong></li>
+</ul>
+
+<p>Retrieves the <code>cordova-plugin-device</code> plugin from the specified directory, adds it to the project, and updates the <code>package.json</code> file.</p>
+
+<h3>Mass Saving of Plugins on an Existing Project</h3>
+
+<p>If you have a pre-existing project and you want to save all currently added plugins in the project, you can use:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin save
</code></pre></div>
-<h3>Removing plugins</h3>
+<h3>Removing Plugins</h3>
-<p>It is also possible to delete from config.xml and package.json during the command 'cordova plugin remove' :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>cordova plugin remove <plugin>
+<p>It is possible to delete a plugin from <code>config.xml</code> and <code>package.json</code> with one of the following commands:</p>
+<div class="highlight"><pre><code class="language-bash" data-lang="bash">cordova plugin remove <plugin>
+cordova plugin rm <plugin>
</code></pre></div>
-<p>For example:</p>
+<p>For Example:</p>
<ul>
-<li><strong>'cordova plugin remove cordova-plugin-console'</strong> => Removes the console plugin from the project and deletes its entry from config.xml and package.json.</li>
+<li><strong><code>cordova plugin remove cordova-plugin-device</code></strong></li>
</ul>
-<h3>Restoring plugins</h3>
+<p>Removes the <code>cordova-plugin-device</code> plugin from the project and deletes its entry from <code>package.json</code>.</p>
+
+<p><em>Note: If the plugin definition existed in <code>config.xml</code> from a previous version of Cordova CLI, it will also be removed from <code>config.xml</code>.</em></p>
+
+<h3>Restoring Plugins</h3>
+
+<p>Plugins are automatically restored from <code>package.json</code> and <code>config.xml</code> when executing the <strong><code>cordova prepare</code></strong> command.</p>
+
+<p>If a plugin is defined in both files, the information defined in <code>package.json</code> is used as the source of truth.</p>
-<p>Plugins are automatically restored from package.json and config.xml when the <strong>'cordova prepare'</strong> command is run. After prepare is run, package.json and config.xml should contain identical plugins and versions.</p>
+<p>After <code>prepare</code>, any plugins restored from <code>config.xml</code> will update the <code>package.json</code> file to reflect the values taken from <code>config.xml</code>.</p>
-<p>If you add a plugin without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, <strong>if found</strong>. In case of conflicts, package.json is given precedence over config.xml.</p>
+<p>If you add a plugin without specifying a <code><version | folder | git_url></code>, the version that will be installed is taken from <code>package.json</code> or <code>config.xml</code>.</p>
+
+<p><strong>If discovered</strong> in both files, <code>package.json</code> is given higher priority over <code>config.xml</code>.</p>
<p>Example:</p>
-<p>Suppose your config.xml file contains the following entry:</p>
+<p>Suppose your <code>config.xml</code> file contains the following entry:</p>
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version='1.0' encoding='utf-8'?></span>
...
- <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-console"</span> <span class="na">spec=</span><span class="s">"0.2.11"</span> <span class="nt">/></span>
+ <span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-device"</span> <span class="na">spec=</span><span class="s">"2.0.1"</span> <span class="nt">/></span>
...
<span class="nt"></ xml></span>
</code></pre></div>
-<p>If you run the command <strong>'cordova plugin add cordova-plugin-console'</strong> (no version/folder/git_url specified), the plugin 'cordova-plugin-console@0.2.11' (as retrieved from config.xml) will be installed.</p>
+<p>If you run the command <strong><code>cordova plugin add cordova-plugin-device</code></strong> with no <code><version | folder | git_url></code> specified, the platform <code>cordova-plugin-device@2.0.1</code> will be retrieved and installed.</p>
-<p><strong>Example for order of precedence for restoring plugins:</strong></p>
+<p><strong>Example Order of Priority for Restoring Plugins:</strong></p>
-<p>Supposed your config.xml has this plugin and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><plugin <span class="nv">name</span><span class="o">=</span><span class="s2">"cordova-plugin-splashscreen"</span>/>
-</code></pre></div>
-<p>Suppose your package.json has this plugin and version:</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span> : <span class="o">{}</span> <span class="o">}</span> <span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span>: <span class="s2">"1.0.0"</span><span class="o">}</span>
-</code></pre></div>
-<p>When prepare is run, package.jsonâs contents are giving precedence and both config.xml and package.json are updated so that they have identical plugins and variables. Notice how package.json's version (1.0.0) is now in config.xml.</p>
+<p>Suppose you have defined in <code>config.xml</code> and <code>package.json</code> a plugin and version as follows:</p>
-<p>After running <strong>'cordova prepare'</strong> , the resulting config.xml looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><plugin <span class="nv">name</span><span class="o">=</span><span class="s2">"cordova-plugin-splashscreen"</span> <span class="nv">spec</span><span class="o">=</span><span class="s2">"1.0.0"</span>/>
-</code></pre></div>
-<p>After running <strong>'cordova prepare'</strong> , the resulting package.json looks like :</p>
-<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="s2">"cordova"</span>: <span class="o">{</span><span class="s2">"plugins"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span> : <span class="o">{}</span> <span class="o">}</span> <span class="o">}</span>,<span class="s2">"dependencies"</span>: <span class="o">{</span><span class="s2">"cordova-plugin-splashscreen"</span>: <span class="s2">"1.0.0"</span><span class="o">}</span>
+<p><strong><code>config.xml</code></strong>:</p>
+<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><plugin</span> <span class="na">name=</span><span class="s">"cordova-plugin-splashscreen"</span><span class="nt">/></span>
</code></pre></div>
+<p><strong><code>package.json</code></strong>:</p>
+<div class="highlight"><pre><code class="language-json" data-lang="json"><span class="s2">"cordova"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"plugins"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
+ </span><span class="s2">"cordova-plugin-splashscreen"</span><span class="w">
+ </span><span class="p">]</span><span class="w">
+</span><span class="p">},</span><span class="w">
+</span><span class="s2">"devDependencies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
+ </span><span class="s2">"cordova-plugin-splashscreen"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div>
+<p>When <code>prepare</code> is executed, the version from <code>package.json</code> has higher priority over <code>config.xml</code> and version <code>1.0.0</code> will be installed.</p>
+
</div>
</div>
Modified: cordova/site/public/feed.xml
URL: http://svn.apache.org/viewvc/cordova/site/public/feed.xml?rev=1859075&r1=1859074&r2=1859075&view=diff
==============================================================================
--- cordova/site/public/feed.xml (original)
+++ cordova/site/public/feed.xml Fri May 10 10:26:40 2019
@@ -6,8 +6,8 @@
</description>
<link>https://cordova.apache.org/</link>
<atom:link href="https://cordova.apache.org/feed.xml" rel="self" type="application/rss+xml"/>
- <pubDate>Fri, 10 May 2019 09:36:21 +0000</pubDate>
- <lastBuildDate>Fri, 10 May 2019 09:36:21 +0000</lastBuildDate>
+ <pubDate>Fri, 10 May 2019 10:06:29 +0000</pubDate>
+ <lastBuildDate>Fri, 10 May 2019 10:06:29 +0000</lastBuildDate>
<generator>Jekyll v2.5.3</generator>
<item>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org