[
https://issues.apache.org/jira/browse/CB-10526?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15154648#comment-15154648
]
ASF GitHub Bot commented on CB-10526:
-------------------------------------
Github user rakatyal commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/505#discussion_r53500398
--- Diff: www/docs/en/dev/guide/platforms/ios/index.md ---
@@ -72,192 +60,124 @@ There are two ways to download Xcode:
which requires registration as an Apple Developer.
Once Xcode is installed, several command-line tools need to be enabled
-for Cordova to run. From the __Xcode__ menu, select __Preferences__,
-then the __Downloads__ tab. From the __Components__ panel, press the
-__Install__ button next to the __Command Line Tools__ listing.
+for Cordova to run. From the command line, run:
+``` xcode-select --install```
-## Install Deploy Tools
+### Deployment Tools
-Run from comman-line terminal:
+The [ios-sim](https://www.npmjs.org/package/ios-sim) and
+[ios-deploy](https://www.npmjs.org/package/ios-deploy) tools - allows you
+to launch iOS apps into the iOS Simulator and iOS Device from the
command-line.
+
+To install them, run the following from command-line terminal:
$ npm install -g ios-sim
$ npm install -g ios-deploy
-## Create a New Project
-
-Use the `cordova` utility to set up a new project, as described in The
-Cordova [The Command-Line Interface](../../cli/index.html). For example,
in a source-code directory:
+## Project Configuration
- $ cordova create hello com.example.hello "HelloWorld"
- $ cd hello
- $ cordova platform add ios
- $ cordova prepare # or "cordova build"
+Installing Xcode will mostly set everything needed to get started.
-## Deploy the app
-
-To deploy the app on a connected iOS device:
-
- $ cordova run ios --device
-To deploy the app on a default iOS emulator:
-
- $ cordova emulate ios
-
-You can use __cordova run ios --list__ to see all available targets and
-__cordova run ios --target=target_name__ to run application on a specific
-device or emulator (for example, `cordova run ios --target="iPhone-6"`).
-
-You can also use __cordova run --help__ to see additional build and run
-options.
-
-## Open a Project in the SDK
-
-Once ios platform is added to your project, you can open it from
-within Xcode. Double-click to open the
`hello/platforms/ios/hello.xcodeproj`
-file. The screen should look like this:
-
-
+## Signing an App
-## Deploy to Emulator
+First, you should read through the [Code Signing Support
Page](https://developer.apple.com/support/code-signing/)
+and the [App Distribution
Workflows](https://developer.apple.com/library/prerelease/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html).
-To preview the app in the iOS emulator:
+### Using Flags
-1. Make sure the _.xcodeproj_ file is selected in the left panel.
+To sign an app, you need the following parameters:
-2. Select the __hello__ app in the panel immediately to the right.
+| Parameter | Flag | Description
+|--------------------------|--------------------------|-----------------------------------
+| Code Sign Identity | `--codeSignIdentity` | Code signing
identity to use for signing. It can be created with Xcode and added to your
keychain.
+| Provisioning Profile | `--provisioningProfile` | GUID of the
provisioning profile to be used for signing. It is copied here on your Mac:
~/Library/MobileDevice/Provisioning\ Profiles/. Opening it in a text editor,
you can find the GUID which needs to be specified here.
+| Code Sign Resource Rules | `--codesignResourceRules`| (Optional) Used to
control which files in a bundle should be sealed by a code signature. For more
details, read [The OS X Code Signing In Depth
article](https://developer.apple.com/library/mac/technotes/tn2206/_index.html#//apple_ref/doc/uid/DTS40007919-CH1-TNTAG206)
-3. Select the intended device from the toolbar's __Scheme__ menu, such
- as the iPhone 6.0 Simulator as highlighted here:
+### Using build.json
- 
+Alternatively, you could specify them in a build configuration file
(`build.json`)
+using the `--buildConfig` argument to the same commands. Here's a sample
of a
+build configuration file:
-4. Press the __Run__ button that appears in the same toolbar to the
- left of the __Scheme__. That builds, deploys and runs the
- application in the emulator. A separate emulator application opens
- to display the app:
+ {
+ "ios": {
+ "debug": {
+ "codeSignIdentity": "iPhone Development",
+ "provisioningProfile":
"926c2bd6-8de9-4c2f-8407-1016d2d12954"
+ },
+ "release": {
+ "codeSignIdentity": "iPhone Distribution"
+ "provisioningProfile":
"70f699ad-faf1-4adE-8fea-9d84738fb306"
+ }
+ }
+ }
+
+### Using xcrun
- 
+You can also sign from the command line using the following command:
- Only one emulator may run at a time, so if you want to test the app
- in a different emulator, you need to quit the emulator application
- and run a different target within Xcode.
+```
+ xcrun -sdk iphoneos PackageApplication -v
/home/user/app/build/device/MyApp.app -o /home/user/app/build/device/MyApp.ipa
--sign "iPhone Development" --embed "7151ab45-6085-4ea1-9bcd-022b5cebe44b"
+```
-Xcode comes bundled with emulators for the latest versions of iPhone
-and iPad. Older versions may be available from the __Xcode →
-Preferences → Downloads → Components__ panel.
+## Debugging
-## Deploy to Device
+For details on the debugging tools that come with Xcode, see this
[article](https://developer.apple.com/support/debugging)
+and this [video](https://developer.apple.com/videos/play/wwdc2014-413/).
-For details about various requirements to deploy to a device, refer
-to the _Launch Your App On Devices_ section of
-Apple's
-[About App Distribution
Workflows](https://developer.apple.com/library/prerelease/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html).
-Briefly, you need to do the following before deploying:
+### Open a Project within Xcode
-1. Join the Apple iOS Developer Program.
+Cordova for iOS projects can be opened in Xcode. This can be useful if
+you wish to use Xcode built in debugging/profiling tools or if you are
+developing iOS plugins. Please note that when opening your project in
Xcode,
+it is recommended that you do NOT edit your code in the IDE. This will
edit the code
+in the ```platforms``` folder of your project (not ```www```), and changes
are liable to be overwritten.
+Instead, edit the ```www``` folder and copy over your changes by running
```cordova build```.
-2. Create a _Provisioning Profile_ within the
- [iOS Provisioning
Portal](https://developer.apple.com/ios/manage/overview/index.action).
- You can use its _Development Provisioning Assistant_ to create and
- install the profile and certificate Xcode requires.
+Plugin developers wishing to edit their native code in the IDE should use
the ```--link``` flag when adding their
+plugin to the project via cordova plugin add. This will link the files so
that changes to the plugin files in the
+platforms folder are reflected in your plugin's source folder (and vice
versa).
-3. Verify that the _Code Signing_ section's _Code Signing Identity_
- within the project settings is set to your provisioning profile
- name.
-
-To deploy to the device:
-
-1. Use the USB cable to plug the device into your Mac.
-
-2. Select the name of the project in the Xcode window's __Scheme__
- drop-down list.
-
-3. Select your device from the __Device__ drop-down list. If it is
- plugged in via USB but still does not appear, press the
- __Organizer__ button to resolve any errors.
-
-4. Press the __Run__ button to build, deploy and run the application
- on your device.
-
-## Common Problems
-
-__Deprecation Warnings__: When an application programming interface
-(API) is changed or replaced by another API, it is marked as
-_deprecated_. The API still works in the near term, but is eventually
-removed. Some of these deprecated interfaces are reflected in Apache
-Cordova, and Xcode issues warnings about them when you build and
-deploy an application.
-
-Xcode's warning about the `invokeString` method concerns functionality
-that launches an app from a custom URL. While the mechanism to load
-from a custom URL has changed, this code is still present to provide
-backwards functionality for apps created with older versions of
-Cordova. The sample app does not use this functionality, so these
-warnings can be ignored. To prevent these warnings from appearing,
-remove the code that references the deprecated invokeString API:
-
-* Edit the _Classes/MainViewController.m_ file, surround the following
- block of code with `/*` and `*/` comments as shown below, then type
- __Command-s__ to save the file:
-
- (void)webViewDidFinishLoad:(UIWebView*)theWebView
- {
- // only valid if ___PROJECTNAME__-Info.plist specifies a protocol
to handle
- /*
- if (self.invokeString) {
- // this is passed before the deviceready event is fired, so you
can access it in js when you receive deviceready
- NSLog(@"DEPRECATED: window.invokeString - use the
window.handleOpenURL(url) function instead, which is always called when the app
is launched through a custom scheme url.");
- NSString* jsString = [NSString stringWithFormat:@"var
invokeString = \"%@\";", self.invokeString];
- [theWebView stringByEvaluatingJavaScriptFromString:jsString];
- }
- */
- // Black base color for background matches the native apps
- theWebView.backgroundColor = [UIColor blackColor];
-
- return [super webViewDidFinishLoad:theWebView];
- }
-
-* Edit the _Classes/AppViewDelegate.m_ file, comment out the following
- line by inserting a double slash as shown below, then type
- __Command-s__ to save the file:
-
- //self.viewController.invokeString = invokeString;
-
-* Press __Command-b__ to rebuild the project and eliminate the warnings.
-
-<!-- Does this fix only last until the next "cordova prepare"? -->
-
-__Missing Headers__: Compilation errors relating to missing headers
-result from problems with the build location, and can be fixed
-via Xcode preferences:
-
-1. Select __Xcode → Preferences → Locations__.
+Once the ios platform is added to your project and built using ```cordova
build```, you can open it from
+within Xcode. Double-click to open the
`${PROJECT_NAME}/platforms/ios/${PROJECT_NAME}.xcodeproj`
+file. The screen should look like this:
-2. In the __Derived Data__ section, press the __Advanced__ button and
- select __Unique__ as the __Build Location__ as shown here:
+
- 
+## Platform Centered Workflow
-This is the default setting for a new Xcode install, but it may be set
-differently following an upgrade from an older version of Xcode.
+cordova-ios includes a number of scripts that allow the platform to be used
+without the full Cordova CLI. This development path may offer you a greater
+range of development options in certain situations than the cross-platform
CLI
+tool described in [The Command-Line Interface](../../cli/index.html).
+For example, you need to use shell tools when deploying a custom
+Cordova WebView alongside native components. Before using this
+development path, you must still configure the SDK environment
+as described in [Requirements and Support](#link-requirements-and-support)
+above.
-For further information, consult Apple's documentation:
+For each of the scripts discussed below, refer to
+[The Command-Line Interface](../../cli/index.html) for more information on
their
+arguments and usage. Each script has a name that matches the corresponding
CLI
+command. For example, `cordova-ios/bin/create` is equivalent to
+`cordova create`.
-* [Start Developing iOS Apps
Today](http://developer.apple.com/library/ios/#referencelibrary/GettingStarted/RoadMapiOS/index.html#//apple_ref/doc/uid/TP40011343)
provides a quick overview of steps for developing iOS Apps.
+To get started, either download the cordova-ios package from
+[npm](https://www.npmjs.com/package/cordova-ios) or
+[Github](https://github.com/apache/cordova-ios).
-* [Member Center home
page](https://developer.apple.com/membercenter/index.action)
- provides links to several iOS technical resources including
- technical resources, the provisioning portal, distribution guides
- and community forums.
+To create a project using this package, run the `create` script in the
`bin`
+folder:
-* [Tools Workflow Guide for
iOS](http://developer.apple.com/library/ios/#documentation/Xcode/Conceptual/ios_development_workflow/00-About_the_iOS_Application_Development_Workflow/introduction.html#//apple_ref/doc/uid/TP40007959)
+ $ cordova-ios/bin/create ...
-* [Xcode User
Guide](http://developer.apple.com/library/ios/#documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/000-About_Xcode/about.html#//apple_ref/doc/uid/TP40010215)
+The created project will have a folder named `cordova` inside that contains
+scripts for the project-specific Cordova commands (e.g. `run`, `build`,
etc.).
+Additionally, The project will feature a structure different from that of a
+normal Cordova project. Notably, `/www` is moved to `/assets/www`.
-* [Session Videos](https://developer.apple.com/videos/wwdc/2012/) from
- the Apple World Wide Developer Conference 2012 (WWDC2012)
+To install plugins in this project, use the [Cordova Plugman
Utility](../../../plugin_ref/plugman.html).
-* The [xcode-select
command](http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/xcode-select.1.html),
- which helps specify the correct version of Xcode if more than one is
installed.
(Mac®, OS X®, Apple®, Xcode®, App Store℠, iPad®, iPhone®, iPod® and
Finder® are Trademarks of Apple Inc.)
--- End diff --
As discussed, we should add an 'Upgrading' section here with reference to
the upgrade article. The upgrade article shouldn't be deleted.
> Improve 'iOS Guide' documentation
> ---------------------------------
>
> Key: CB-10526
> URL: https://issues.apache.org/jira/browse/CB-10526
> Project: Apache Cordova
> Issue Type: Improvement
> Components: Docs, iOS
> Reporter: Omar Mefire
> Assignee: Omar Mefire
>
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
