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:20 UTC
[1/3] docs commit: CB-12591 : updated add/remove/save platform and
plugin info
Repository: cordova-docs
Updated Branches:
refs/heads/master e8ae4e449 -> f523ccbb2
CB-12591 : updated add/remove/save platform and plugin info
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/336883a8
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/336883a8
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/336883a8
Branch: refs/heads/master
Commit: 336883a804b015ba450a2d8786ca74bfff7c79a6
Parents: 75bc963
Author: Audrey So <au...@apache.org>
Authored: Thu Mar 23 10:37:55 2017 -0700
Committer: Audrey So <au...@apache.org>
Committed: Mon May 1 10:19:07 2017 -0700
----------------------------------------------------------------------
.../dev/platform_plugin_versioning_ref/index.md | 73 +++++++++++++-------
1 file changed, 48 insertions(+), 25 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/336883a8/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 b9eb822..5a3bb09 100644
--- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md
+++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md
@@ -27,8 +27,9 @@ 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.
-The 'save' command stores details about the app's platform and plugin versions in config.xml.
-The 'restore' step happens automatically when a **'cordova prepare'** is issued, making use of information previously saved in the config.xml file.
+When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved in config.xml and package.json.
+
+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.
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.
@@ -39,7 +40,7 @@ One scenario where save/restore capabilities come in handy is in large teams tha
To save a platform, you issue the following command :
```bash
-$ cordova platform add <platform[@<version>] | directory | git_url> --save
+$ cordova platform add <platform[@<version>] | directory | git_url>
```
After running the above command, the resulting config.xml looks like :
@@ -51,16 +52,28 @@ After running the above command, the resulting config.xml looks like :
...
</xml>
```
+After running the above command, the resulting package.json looks like :
+
+```bash
+"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 :
+
+```bash
+$ cordova platform add <platform[@<version>] | directory | git_url> --nosave
+```
Some examples :
- * **'cordova platform add android --save'** => retrieves the pinned version of the android platform, adds it to the project and then updates config.xml.
- * **'cordova platform add android@3.7.0 --save'** => retrieves the android platform, version 3.7.0 from npm, adds it to the project and then updates config.xml.
- * **'cordova platform add android@https://github.com/apache/cordova-android.git\u200b --save'** => clones the specified cordova-android git repository, adds the android platform to the project, then updates config.xml and point its version to the specified git-url.
- * **'cordova platform add C:/path/to/android/platform --save'** => retrieves the android platform from the specified directory, adds it to the project, then updates config.xml and point to the directory.
+ * **'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 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
-The '--save' flag described above is only useful when you remember to use it during the platform addition.
+
If you have a pre-existing project and you want to save all the currently added platforms in your project, you can use :
```bash
@@ -68,11 +81,11 @@ $ cordova platform save
```
### Updating / Removing platforms
-It is also possible to update/delete from config.xml during the commands 'cordova platform update' and 'cordova platform remove' :
+It is also possible to update/delete from config.xml and package.json during the commands 'cordova platform update' and 'cordova platform remove' :
```bash
$ cordova platform update <platform[@<version>] | directory | git_url> --save
-$ cordova platform remove <platform> --save
+$ cordova platform remove <platform>
```
Some examples :
@@ -80,14 +93,14 @@ Some examples :
* **'cordova platform update android --save'** => In addition to updating the android platform to the pinned version, update config.xml entry
* **'cordova platform update android@3.8.0 --save'** => In addition to updating the android platform to version 3.8.0, update config.xml entry
* **'cordova platform update /path/to/android/platform --save'** => In addition to updating the android platform to version in the folder, update config.xml entry
- * **'cordova platform remove android --save'** => Removes the android platform from the project and deletes its entry from config.xml.
+ * **'cordova platform remove android'** => Removes the android platform from the project and deletes its entry from config.xml and package.json.
### Restoring platforms
-Platforms are automatically restored from config.xml when the **'cordova prepare'** command is run.
+Platforms are automatically restored from package.json and config.xml when the **'cordova prepare'** command is run. After prepare is run, package.json and config.xml should contain identical platforms and versions.
-If you add a platform without specifying a version/folder/git_url, the version to install is taken from config.xml, **if found**.
+If you add a platform without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, **if found**. In case of conflicts, package.json is given precedence over config.xml.
Example:
@@ -114,7 +127,7 @@ _(The plugin commands are a mirror of the platform commands)_
To save a plugin, you issue the following command :
```bash
-$ cordova plugin add <plugin[@<version>] | directory | git_url> --save
+$ cordova plugin add <plugin[@<version>] | directory | git_url>
```
After running the above command, the resulting config.xml looks like :
@@ -127,16 +140,27 @@ After running the above command, the resulting config.xml looks like :
</xml>
```
+After running the above command, the resulting package.json looks like :
+
+```bash
+"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 :
+
+```bash
+$ cordova plugin add <plugin[@<version>] | directory | git_url> --nosave
+```
Some examples :
- * **'cordova plugin add cordova-plugin-console --save'** => retrieves the pinned version of the console plugin, adds it to the project and then updates config.xml.
- * **'cordova plugin add cordova-plugin-console@0.2.13 --save'** => retrieves the android plugin, version 0.2.13 from npm, adds it to the project and then updates config.xml.
- * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git --save'** => clones the specified console plugin git repository, adds the console plugin to the project, then updates config.xml and point its version to the specified git-url.
- * **'cordova plugin add C:/path/to/console/plugin --save'** => retrieves the console plugin from the specified directory, adds it to the project, then updates config.xml and point to the directory.
+ * **'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 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
-The '--save' flag described above is only useful when you remember to use it during the plugin addition.
+
If you have a pre-existing project and you want to save all currently added plugins in the project, you can use :
```bash
@@ -145,22 +169,21 @@ $ cordova plugin save
### Removing plugins
-It is also possible to delete from config.xml during the command 'cordova plugin remove' :
+It is also possible to delete from config.xml and package.json during the command 'cordova plugin remove' :
```bash
-
-$ cordova plugin remove <plugin> --save
+$ cordova plugin remove <plugin>
```
For example:
- * **'cordova plugin remove cordova-plugin-console --save'** => Removes the console plugin from the project and deletes its entry from config.xml.
+ * **'cordova plugin remove cordova-plugin-console'** => Removes the console plugin from the project and deletes its entry from config.xml and package.json.
### Restoring plugins
-Plugins are automatically restored from config.xml when the **'cordova prepare'** command is run.
+Plugins are automatically restored from package.json and config.xml when the **'cordova prepare'** command is run. After prepare is run, package.json and config.xml should contain identical plugins and versions.
-If you add a plugin without specifying a version/folder/git_url, the version to be installed is taken from config.xml, **if found**.
+If you add a plugin without specifying a version/folder/git_url, the version to install is taken from package.json or config.xml, **if found**. In case of conflicts, package.json is given precedence over config.xml.
Example:
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org
[3/3] docs commit: CB-12591 : added examples and revised basck on
feedback
Posted by st...@apache.org.
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
[2/3] docs commit: CB-12591 : updated info about save and package.json
Posted by st...@apache.org.
CB-12591 : updated info about save and package.json
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/75bc963d
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/75bc963d
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/75bc963d
Branch: refs/heads/master
Commit: 75bc963ddfb6a0582b090ca3e0a4988482d64acd
Parents: e8ae4e4
Author: Audrey So <au...@apache.org>
Authored: Thu Mar 23 07:48:38 2017 -0700
Committer: Audrey So <au...@apache.org>
Committed: Mon May 1 10:19:07 2017 -0700
----------------------------------------------------------------------
www/docs/en/dev/guide/cli/index.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/75bc963d/www/docs/en/dev/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/cli/index.md b/www/docs/en/dev/guide/cli/index.md
index 01e5c1f..3958c3a 100644
--- a/www/docs/en/dev/guide/cli/index.md
+++ b/www/docs/en/dev/guide/cli/index.md
@@ -96,11 +96,11 @@ or any subdirectories:
$ cd hello
```
-Add the platforms that you want to target your app. We will add the 'ios' and 'android' platform and ensure they get saved to `config.xml`:
+Add the platforms that you want to target your app. We will add the 'ios' and 'android' platform and ensure they get saved to `config.xml` and `package.json`:
```bash
-$ cordova platform add ios --save
-$ cordova platform add android --save
+$ cordova platform add ios
+$ cordova platform add android
```
To check your current set of platforms:
@@ -212,7 +212,7 @@ npm and you can search for them on the [plugin search page](/plugins/). Some key
$ cordova plugin search camera
```
-To add the camera plugin, we will specify the npm package name for the camera plugin:
+To add and save the camera plugin to `config.xml` and `package.json`, we will specify the npm package name for the camera plugin:
```
$ cordova plugin add cordova-plugin-camera
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org