license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Please note that Xcode 4.5 is required. To submit to the Apple App Store, you must use the latest shipped version of the iOS SDK, which is iOS 6. The iOS 6 SDK requires Xcode 4.5.
Download and extract the Cordova 2.8.0 source to a permanent folder location on your hard drive (say to ~/Documents/Cordova-2.8.0)
Quit Xcode if it is running.
Navigate to the directory where you put the downloaded source above, using Terminal.app.
Create a new project from the command-line tools - you will have to grab the assets from this new project
Copy the www/cordova.js (note that it does not have a version suffix anymore, the version is in the file itself in the header) file from the new project into your www folder, and delete your www/cordova-2.7.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new cordova.js file
Update any <plugin> tags that are in your config.xml to <feature> tags. Note that existing <plugin> tags will still work, but are deprecated. You can copy this information in the config.xml for a new project. For example:
<plugins> <plugin name="LocalStorage" value="CDVLocalStorage" /> <!-- other plugins --> </plugins> <!-- change to: (note that a <feature> tag is on the same level as <plugins> --> <feature name="LocalStorage"> <param name="ios-package" value="CDVLocalStorage" /> </feature> <!-- other <feature> tags -->
Delete your “CordovaLib” folder, and copy the “CordovaLib” folder from the new project into your project's root folder
Add these two frameworks to your project:
OpenAL ImageIO
Update your project's target Build Settings. Under Linking -> Other Linker Flags, edit “-Obj-C” to be “-ObjC”
Update your project's target Build Settings. Under Linking -> Other Linker Flags, change “-all_load” to be “-force_load ${BUILT_PRODUCTS_DIR}/libCordova.a”. You would only need to do this if you have the problem defined in this issue.
Download and extract the Cordova 2.3.0 source to a permanent folder location on your hard drive (say to ~/Documents/Cordova-2.3.0)
Quit Xcode if it is running.
Navigate to the directory where you put the downloaded source above, using Terminal.app.
Create a new project from the command-line tools - you will have to grab the assets from this new project
Copy the www/cordova-2.3.0.js file from the new project into your www folder, and delete your www/cordova-2.2.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new cordova-2.3.0.js file
Update (or replace, if you never changed the file) your MainViewController.m according to the one from the new project.
Delete your “cordova” folder, and copy the “cordova” folder from the new project into your project's root folder (in 2.3.0, this has new scripts)
Delete your “CordovaLib” folder, and copy the “CordovaLib” folder from the new project into your project's root folder
Convert your Cordova.plist file to config.xml, by running the script bin/cordova_plist_to_config_xml on your project file.
Add the InAppBrowser plugin to your config.xml, by adding this tag under <cordova><plugins>:
<plugin name="InAppBrowser" value="CDVInAppBrowser" />
Note that Objective-C plugins are not whitelisted anymore. To whitelist your connections with the app whitelist, you will need to set the “User-Agent” header of the connection to the same user-agent as the main Cordova WebView. You can get this by accessing the userAgent property off the main view-controller. The main view-controller (CDVViewController) also has a URLisAllowed method for you to check whether a URL will pass the whitelist.
Device API changes:
Launch Terminal.app
Go to the location where you installed Cordova (see Step 1), in the bin sub-folder
Run the script below where the first parameter is the path to your project's .xcodeproj file:
update_cordova_subproject path/to/your/project/xcodeproj
Note that in 2.2.0, the bin/create script will copy in the CordovaLib sub-project into your project now. To have the same kind of setup, just copy in the right CordovaLib into your project folder, and update the CordovaLib sub-project location (relative to the project) in the Xcode File Inspector.
With Cordova 2.1.0, CordovaLib has been upgraded to use Automatic Reference Counting (ARC). You don't need to upgrade to ARC to use CordovaLib, but if you want to upgrade your project to use ARC, please use the Xcode migration wizard from the menu: Edit -> Refactor -> Convert to Objective-C ARC…, de-select libCordova.a, then run the wizard to completion.
Launch Terminal.app
Go to the location where you installed Cordova (see Step 1), in the bin sub-folder
Run the script below where the first parameter is the path to your project's .xcodeproj file:
update_cordova_subproject path/to/your/project/xcodeproj
Install Cordova 2.0.0
Create a new project from the command-line tools - you will have to grab the assets from this new project
Copy the www/cordova-2.0.0.js file from the new project into your www folder, and delete your www/cordova-1.9.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new cordova-2.0.0.js file
Copy the “cordova” folder from the new project into your project's root folder (if you want the project command-line tools)
Add a new entry under Plugins in your Cordova.plist file (under the Supporting Files group) - the key is Device and the value is CDVDevice
Remove Cordova.framework
Remove verify.sh from the Supporting Files group
Select the project icon in the Project Navigator, select your project Target, then select the “Build Settings” tab
Search for “Preprocessor Macros”, then remove all “CORDOVA_FRAMEWORK=1” values
Locate the CordovaLib folder that was installed in your hard-drive under your home folder's Documents sub-folder.
Locate the CordovaLib.xcodeproj file in the CordovaLib folder, then drag and drop the file into your project - it should appear as a sub-project.
Build your project, you should get some errors relating to #import directives
For the #import errors, change any quote-based imports in this style:
#import "CDV.h"
to this brackets-based style:
#import <Cordova/CDV.h>
and remove any #ifdef wrappers around any Cordova imports, they are not needed anymore (the imports are unified now)
Build your project again, and it should not have any #import errors.
Select the project icon in the Project Navigator, select your project Target, then select the “Build Phases” tab
Expand the “Target Dependencies” phase, then select the “+” button
Select the “CordovaLib” target, then select the “Add” button
Expand the first “Link Binary with Libraries” phase (it should already contain a bunch of frameworks), then select the “+” button
Select the libCordova.a static library, then select the “Add” button
Delete the “Run Script” phase.
Select the project icon in the Project Navigator, select your project Target, then select the “Build Settings” tab
Search for “Other Linker Flags”, and add the values -all_load and -Obj-C
Expand the “CordovaLib” sub-project
Locate the “VERSION” file, drag it into your main project (we want to create a link to it, not a copy)
Select the “Create groups for any added folders” radiobutton, then select the “Finish” button
Select the “VERSION” file that you just dragged in a previous step
Press the key combination Option-Command-1 to show the File Inspector (or menuitem View -> Utilities -> Show File Inspector)
Choose “Relative to CORDOVALIB” in the File Inspector for the drop-down menu for Location
Set the Xcode preference “Xcode Preferences -> Locations -> Derived Data -> Advanced…” to “Unique” (this is so the unified headers can be found)
Select the project icon in the Project Navigator, select your Target, then select the “Build Settings” tab
Search for “Header Search Paths”. For that setting, add these three values below (with quotes):
"$(TARGET_BUILD_DIR)/usr/local/lib/include" "$(OBJROOT)/UninstalledProducts/include" "$(BUILT_PRODUCTS_DIR)"
Search for “Other Linker Flags”. For that setting, add this value below:
-weak_framework CoreFoundation
Build your project, it should compile and link with no issues.
Select your project from the Scheme drop-down, and then select “iPhone 5.1 Simulator”
Select the Run button
NOTE:
If your project is not working as expected in the Simulator, please take a note of any errors in the console log in Xcode for clues.
Note:
1.9.0 supports the new “BackupWebStorage” boolean setting in Cordova.plist. By default, this setting is turned on, set it to “false” to turn it off - especially for iOS 6 - see Release Notes - Safari and UIKit Section
If you intend on using the Capture API, you will need the new iPad retina-display assets:
Install Cordova 1.6.1
Make a backup of AppDelegate.m, AppDelegate.h, MainViewController.m, MainViewController.h, and Cordova.plist in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 1.5.0 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m Cordova.plist
Add all the new MainViewController and AppDelegate files into your Xcode project
Copy the www/cordova-1.6.1.js file from the new project into your www folder, and delete your www/cordova-1.5.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new cordova-1.6.1.js file
Add the new Cordova.plist file into your project - this is because the core plugin service names needed to be changed to match the ones from Android and Blackberry, for a unified Cordova JavaScript file (cordova-js).
Integrate any settings, Plugins and ExternalHosts entries that you had in your backed-up Cordova.plist into the new Cordova.plist
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files. Any UIWebViewDelegate or CDVCommandDelegate code in AppDelegate.m will need to go into MainViewController.m now (see commented out sections in that file)
Integrate any project specific code that you have in your backed-up MainViewController.h and MainViewController.m into the new MainViewController files
Click on the project icon in the Project Navigator, select your Project, then select the “Build Settings” tab
Enter “Compiler for C/C++/Objective-C” in the search field
Select the “Apple LLVM Compiler 3.1” value
Install Cordova 1.5.0
Create a new project and run it once - you will have to grab assets from this new project
Copy the www/cordova-1.5.0.js file from the new project into your www folder, and delete your www/phonegap-1.4.x.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new Cordova cordova-1.5.0.js file
Find “PhoneGap.framework” in your Project Navigator, select it
Press the Delete key and delete the “PhoneGap.framework” reference in the Project Navigator
Press the key combination Option-Command-A, which should drop down a sheet to add files to your project (the “Add Files...” sheet). Make sure the “Created groups for any added folders” radio-button is selected
Press the key combination Shift-Command-G, which should drop down another sheet for you to go to a folder (the “Go to the folder:” sheet)
Enter “/Users/Shared/Cordova/Frameworks/Cordova.framework” in the “Go to the folder:” sheet and then press the “Go” button
Press the “Add” button in the “Add Files...” sheet
Select “Cordova.framework” in the Project Navigator
Press the key combination Option-Command-1 to show the File Inspector
Choose “Absolute Path” in the File Inspector for the drop-down menu for Location
Press the key combination Option-Command-A, which should drop down a sheet to add files to your project (the “Add Files...” sheet). Make sure the “Created groups for any added folders” radio-button is selected
Press the key combination Shift-Command-G, which should drop down another sheet for you to go to a folder (the “Go to the folder:” sheet)
Enter “~/Documents/CordovaLib/Classes/deprecated” in the “Go to the folder:” sheet and then press the “Go” button
Press the “Add” button in the “Add Files...” sheet
In your AppDelegate.h, AppDelegate.m, and MainViewController.h files - replace the whole #ifdef PHONEGAP_FRAMEWORK block with:
#import "CDVDeprecated.h"
Click on the project icon in the Project Navigator, select your Target, then select the “Build Settings” tab
Search for “Framework Search Paths”
Replace the existing value with “/Users/Shared/Cordova/Frameworks”
Search for “Preprocessor Macros”
For the first (combined) value, replace the value with “CORDOVA_FRAMEWORK=YES”
Select the “Build Phases” tab
Expand “Run Script”
Replace any occurrences of PhoneGap with Cordova
Find your “PhoneGap.plist” file in the Project Navigator, and click on the filename once to enter name edit mode
Rename “PhoneGap.plist” to “Cordova.plist”
Right-click on “Cordova.plist” and choose “Open As” --> “Source Code”
Press Option-Command-F, choose “Replace” from the drop-down on the top left of the Source window
Enter com.phonegap for the Find string, and org.apache.cordova for the Replace string - then press the “Replace All” button
Enter PG for the Find string, and CDV for the Replace string - then press the “Replace All” button
Press Command-B to build, you will still have deprecations that you can get rid of in the future (see CDVDeprecated.h - replace classes in your code that use PG* to CDV*, for example)
Install Cordova 1.4.0
Make a backup of AppDelegate.m and AppDelegate.h in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 1.3.0 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m MainViewController.xib
Add all the MainViewController files into your Xcode project
Copy the www/phonegap-1.4.0.js file from the new project into your www folder, and delete your www/phonegap-1.3.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new phonegap-1.4.0.js file
Add a new entry under Plugins in your PhoneGap.plist file - key is com.phonegap.battery and the value is PGBattery
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files
Install Cordova 1.3.0
Make a backup of AppDelegate.m and AppDelegate.h in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 1.2.0 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m MainViewController.xib
Add all the MainViewController files into your Xcode project
Copy the www/phonegap-1.3.0.js file from the new project into your www folder, and delete your www/phonegap-1.2.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new phonegap-1.3.0.js file
Add a new entry under Plugins in your PhoneGap.plist file - key is com.phonegap.battery and the value is PGBattery
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files
Install Cordova 1.2.0
Make a backup of AppDelegate.m and AppDelegate.h in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 1.1.0 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m MainViewController.xib
Add all the MainViewController files into your Xcode project
Copy the www/phonegap-1.2.0.js file from the new project into your www folder, and delete your www/phonegap-1.1.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new phonegap-1.2.0.js file
Add a new entry under Plugins in your PhoneGap.plist file - key is com.phonegap.battery and the value is PGBattery
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files
Install Cordova 1.1.0
Make a backup of AppDelegate.m and AppDelegate.h in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 1.0.0 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m MainViewController.xib
Add all the MainViewController files into your Xcode project
Copy the www/phonegap-1.1.0.js file from the new project into your www folder, and delete your www/phonegap-1.0.0.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new phonegap-1.1.0.js file
Add a new entry under Plugins in your PhoneGap.plist file - key is com.phonegap.battery and the value is PGBattery
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files
Install Cordova 1.0.0
Make a backup of AppDelegate.m and AppDelegate.h in your project
Create a new project - you will have to grab assets from this new project
Copy these files from the new project into your 0.9.6 based project folder on disk, replacing any old files (backup your files first from step 2 above):
AppDelegate.h AppDelegate.m MainViewController.h MainViewController.m MainViewController.xib
Add all the MainViewController files into your Xcode project
Copy the www/phonegap-1.0.0.js file from the new project into your www folder, and delete your www/phonegap-0.9.6.js file
Update the Cordova script reference in your www/index.html file (and any other files that contain the script reference) to point to the new phonegap-1.0.0.js file
Add a new entry under Plugins in your PhoneGap.plist file - key is com.phonegap.battery and the value is PGBattery
Integrate any project specific code that you have in your backed-up AppDelegate.h and AppDelegate.m into the new AppDelegate files