docs: improve CLI pass-through argument documentation for Windows (#1336) - #1530
rishi919-rgb wants to merge 1 commit into
Conversation
|
I would leave the documentation examples to use just |
2a20840 to
7ae7767
Compare
|
Thanks for the feedback @GitToTheHub! That makes complete sense. I have updated the changes accordingly:
The commit has been amended and force-pushed. |
| > ```bash | ||
| > cordova build android --release "--" --packageType=apk | ||
| > ``` | ||
| > See the [Android Platform Guide](../../guide/platforms/android/index.html#signing-an-app) and [iOS Platform Guide](../../guide/platforms/ios/index.html) for available platform-specific flags. |
There was a problem hiding this comment.
See the Android Platform Guide and iOS Platform Guide for available platform-specific flags.
Should not be in the note, since this is a general information of the Passing Platform-Specific Arguments section and not specific to Windows. You could add this under See Also:. Also link the Android Platform Guide to just index.html as you did for iOS.
There was a problem hiding this comment.
You could add to Example: the platforms the example is for, like **Example Unix/macOS:**
There was a problem hiding this comment.
You could add to Example: the platforms the example is for, like Example Unix/macOS:
| cordova run android -- --gradleArg=-PcdvMinSdkVersion=20 | ||
| ``` | ||
|
|
||
| _**Note:** The example above is for Unix/macOS shells. On Windows (Command Prompt and PowerShell), the intermediate `--` separator must be enclosed in quotation marks (`"--"`), e.g. `cordova run android "--" --gradleArg=-PcdvMinSdkVersion=20`._ |
There was a problem hiding this comment.
Use the same style as of for www/docs/en/latest/guide/cli/index.md like:
> **Note for Windows users:** On Windows (Command Prompt and PowerShell), the `--` separator must be enclosed in quotation marks (`"--"`) so that the shell forwards the arguments to platform build scripts correctly, for example:
> ```bash
> cordova build android --release "--" --packageType=apk
> ```| By default, JVM args has a value of `-Xmx2048m`. To increase the maximum allowed memory, use the `-Xmx` JVM arg. Example given below: | ||
|
|
||
| ``` | ||
| ```bash |
There was a problem hiding this comment.
Add **Example Unix/macOS:** here
| @@ -611,7 +613,14 @@ _**Note**: You should use double `--` to indicate that these are platform-specif | |||
|
|
|||
| Example: | |||
There was a problem hiding this comment.
add the platforms of the example here Example (Unix/macOS):
|
|
||
| **Note**: You should use double `--` to indicate that these are platform-specific arguments, for example: | ||
|
|
||
| `cordova run ios --release -- --codeSignIdentity="iPhone Developer" --developmentTeam=FG35JLLMXX4A --packageType=development`. |
There was a problem hiding this comment.
Add Example (Unix/macOS): here
| cordova run android -- --gradleArg=-PcdvMinSdkVersion=20 | ||
| ``` | ||
|
|
||
| _**Note:** The example above is for Unix/macOS shells. On Windows (Command Prompt and PowerShell), the intermediate `--` separator must be enclosed in quotation marks (`"--"`), e.g. `cordova run android "--" --gradleArg=-PcdvMinSdkVersion=20`._ |
There was a problem hiding this comment.
Rather than explaining each time the "--" exception for Windows, you could directly add an example for Windows like:
**Example Windows:**
```bash
cordova run android "--" --gradleArg=-PcdvMinSdkVersion=20
…ache#1336) - Keep standard CLI examples using unquoted -- separator - Add dedicated notes explaining the quotation requirement ("--") for Windows (Command Prompt and PowerShell) - Add Passing Platform-Specific Arguments section to the Cordova CLI guide with notes for Windows users - Fixes apache#1336
7ae7767 to
9cf359a
Compare
|
Thanks again for the thorough review and helpful suggestions @GitToTheHub! I have updated the PR to incorporate all of your feedback:
The commit has been amended and force-pushed. |
2 participants
Platforms affected
Documentation / CLI (All platforms, specifically Windows Command Prompt and PowerShell, Android, iOS)
Motivation and Context
Fixes #1336
On Windows using Command Prompt or PowerShell, passing platform-specific arguments using the intermediate
--separator requires enclosing the--in quotation marks ("--"). Without quotes, PowerShell throws syntax/parse errors or treats--as a parameter terminator, leading to argument forwarding failures (as reported in apache/cordova-android#1671).Description
Following reviewer feedback:
--separator (Unix/macOS).--separator must be enclosed in quotation marks ("--"), with accompanying examples.guide/cli/index.md) with concrete examples for Android (Gradle parameters, signing / packageType) and links to platform guides.Testing
npm test(npm run lint), passing with 0 errors.Checklist
(platform)if this change only applies to one platform (e.g.(android))