cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rakatyal <>
Subject [GitHub] cordova-docs pull request: CB-10526: iOS Guide Improvements
Date Fri, 19 Feb 2016 18:48:00 GMT
Github user rakatyal commented on a diff in the pull request:
    --- Diff: www/docs/en/dev/guide/platforms/ios/ ---
    @@ -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]( and 
    +[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
    +## 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
    -## 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:
    -![]({{ site.baseurl }}/static/img/guide/platforms/ios/helloworld_project.png)
    +## Signing an App
    -## Deploy to Emulator
    +First, you should read through the [Code Signing Support Page](

    +and the [App Distribution Workflows](
    -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
    +| 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](

    -3. Select the intended device from the toolbar's __Scheme__ menu, such
    -   as the iPhone 6.0 Simulator as highlighted here:
    +### Using build.json
    -   ![]({{ site.baseurl }}/static/img/guide/platforms/ios/select_xcode_scheme.png)
    +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
    -   ![]({{ site.baseurl }}/static/img/guide/platforms/ios/HelloWorldStandard.png)
    +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/ -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 &rarr;
    -Preferences &rarr; Downloads &rarr; Components__ panel.
    +## Debugging
    -## Deploy to Device
    +For details on the debugging tools that come with Xcode, see this [article](
    +and this [video](
    -For details about various requirements to deploy to a device, refer
    -to the _Launch Your App On Devices_ section of
    -[About App Distribution Workflows](
    -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](
    -   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
    -          NSString* jsString = [NSString stringWithFormat:@"var 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 &rarr; Preferences &rarr; 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:
    +![]({{ site.baseurl }}/static/img/guide/platforms/ios/helloworld_project.png)
    -   ![]({{ site.baseurl }}/static/img/guide/platforms/ios/xcode_build_location.png)
    +## 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)
    -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](
provides a quick overview of steps for developing iOS Apps.
    +To get started, either download the cordova-ios package from
    +[npm]( or
    -* [Member Center home page](
    -   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`
    -* [Tools Workflow Guide for iOS](
    +    $ cordova-ios/bin/create ...
    -* [Xcode User Guide](
    +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]( 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](,
    -  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.

If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at or file a JIRA ticket
with INFRA.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message