You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2017/05/01 21:45:22 UTC
[3/3] docs commit: CB-12591 : added examples and revised basck on
feedback
CB-12591 : added examples and revised basck on feedback
This closes #689
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/f523ccbb
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/f523ccbb
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/f523ccbb
Branch: refs/heads/master
Commit: f523ccbb2e66f068047703178de287bf6f707ccf
Parents: 336883a
Author: Audrey So <au...@apache.org>
Authored: Wed Mar 29 16:06:23 2017 -0700
Committer: Steve Gill <st...@gmail.com>
Committed: Mon May 1 23:45:12 2017 +0200
----------------------------------------------------------------------
.../dev/platform_plugin_versioning_ref/index.md | 59 +++++++++++++++++---
1 file changed, 52 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f523ccbb/www/docs/en/dev/platform_plugin_versioning_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md
index 5a3bb09..653933a 100644
--- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md
+++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md
@@ -27,7 +27,7 @@ From version 4.3.0 onwards, Cordova provides the ability to save and restore pla
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.
-When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved in config.xml and package.json.
+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 `cordova plugin add|remove ...` and `cordova platform add|remove ...` to avoid any out of sync issues.
The 'restore' step happens automatically when a **'cordova prepare'** is issued, making use of information previously saved in the config.xml and package.json files.
@@ -55,7 +55,7 @@ After running the above command, the resulting config.xml looks like :
After running the above command, the resulting package.json looks like :
```bash
-"cordova": {"platforms": ["android",]},"dependencies": {"cordova-android": "~4.0.0",}
+"cordova": {"platforms": ["android"]},"dependencies": {"cordova-android": "^4.0.0"}
```
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 :
@@ -67,13 +67,12 @@ Some examples :
* **'cordova platform add android'** => retrieves the pinned version of the android platform, adds it to the project and then updates config.xml and package.json.
* **'cordova platform add android@3.7.0'** => retrieves the android platform, version 3.7.0 from npm, adds it to the project and then updates config.xml and package.json.
- * **'cordova platform add android@https://github.com/apache/cordova-android.git\u200b'** => clones the specified cordova-android 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.
+ * **'cordova platform add https://github.com/apache/cordova-android.git'** => 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.
* **'cordova platform add C:/path/to/android/platform'** => 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.
* **'cordova platform add android --nosave'** => retrieves the pinned version of the android platform, adds it to the project, but does not add it to config.xml or package.json.
* **'cordova platform remove android --nosave'** => removes the android platform from the project, but does not remove it from config.xml or package.json.
### Mass saving platforms on an existing project
-
If you have a pre-existing project and you want to save all the currently added platforms in your project, you can use :
```bash
@@ -116,8 +115,30 @@ Suppose your config.xml file contains the following entry:
If you run the command **'cordova platform add android'** (no version/folder/git_url specified), the platform 'android@3.7.0' (as retrieved from config.xml) will be installed.
+**Example for order of precedence for restoring platforms:**
+
+Suppose your config.xml has this platform and version:
+```bash
+<engine name="android" spec=\u201c1.0.0\u201d />
+```
+
+Suppose your package.json has this platform and version:
+
+```bash
+"cordova": {"platforms": ["android"]},"dependencies": {"cordova-android": "4.0.0"}
+```
+
+When prepare is run, package.json\u2019s 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 **replaced** config.xml's version (1.0.0).
+After running **'cordova prepare'** , the resulting config.xml looks like :
+```bash
+<engine name="android" spec=\u201c4.0.0\u201d />
+```
+After running **'cordova prepare'** , the resulting package.json looks like :
+```bash
+"cordova": {"platforms": ["android",]},"dependencies": {"cordova-android": "4.0.0"}
+```
---
## Plugin Versioning
@@ -143,7 +164,7 @@ After running the above command, the resulting config.xml looks like :
After running the above command, the resulting package.json looks like :
```bash
-"cordova": {"plugins": ["cordova-plugin-console",]},"dependencies": {"cordova-plugin-console": "~1.0.0",}
+"cordova": {"plugins": ["cordova-plugin-console"]},"dependencies": {"cordova-plugin-console": "^1.0.0"}
```
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 :
@@ -156,11 +177,10 @@ Some examples :
* **'cordova plugin add cordova-plugin-console'** => retrieves the pinned version of the console plugin, adds it to the project and then updates config.xml and package.json.
* **'cordova plugin add cordova-plugin-console@0.2.13'** => retrieves the android plugin, version 0.2.13 from npm, adds it to the project and then updates config.xml and package.json.
- * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git'** => clones the specified console plugin 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.
+ * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git'** => 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.
* **'cordova plugin add C:/path/to/console/plugin'** => 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.
### Mass saving plugins on an existing project
-
If you have a pre-existing project and you want to save all currently added plugins in the project, you can use :
```bash
@@ -199,3 +219,28 @@ Suppose your config.xml file contains the following entry:
If you run the command **'cordova plugin add cordova-plugin-console'** (no version/folder/git_url specified), the plugin 'cordova-plugin-console@0.2.11' (as retrieved from config.xml) will be installed.
+**Example for order of precedence for restoring plugins:**
+
+Supposed your config.xml has this plugin and version:
+
+```bash
+<plugin name="cordova-plugin-splashscreen"/>
+```
+Suppose your package.json has this plugin and version:
+
+```bash
+"cordova": {"plugins": {"cordova-plugin-splashscreen" : {} } },"dependencies": {"cordova-plugin-splashscreen": "1.0.0"}
+```
+When prepare is run, package.json\u2019s 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.
+
+After running **'cordova prepare'** , the resulting config.xml looks like :
+
+```bash
+<plugin name="cordova-plugin-splashscreen" spec="1.0.0"/>
+```
+
+After running **'cordova prepare'** , the resulting package.json looks like :
+
+```bash
+"cordova": {"plugins": {"cordova-plugin-splashscreen" : {} } },"dependencies": {"cordova-plugin-splashscreen": "1.0.0"}
+```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org