Broken PhoneGap 3.0.0 Installation and Documentation

// TLDR – start

• Phonegap 3.0.0 documentation is broken.
• Download the project template
• replace your www folder with that in the project template
• Use “phonegap local build ios”
• Xcode project files in platforms/ios/HelloWorld.xcodeproj

// TLDR – end

So I go to install Phonegap for while playing around with developing on iOS and find that they have yet again changed their process of installation and setting up projects. While that annoys me somewhat, what really annoys me is that the installation and documentation is broken.

Firstly the following command from the documentation (http://docs.phonegap.com/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface)

$ phonegap create hello com.example.hello HelloWorld

Gives me an error

[error] downloaded www assets in /Users/thewheat/.cordova/lib/www/phonegap/3.0.0/www does not contain index.html, or www subdir with index.html

and it just created a few empty folders

$ ls hello/*
hello/merges:

hello/platforms:

hello/plugins:

hello/www:

Thinking it was just some weird error, I just continued on to the iOS documentation (http://docs.phonegap.com/en/edge/guide_platforms_ios_index.md.html#iOS%20Platform%20Guide_open_a_project_in_the_sdk)

$ cordova create hello com.example.hello "HelloWorld"
$ cd hello
$ cordova platform add ios
$ cordova prepare              # or "cordova build"

This still references “cordova” which was the name of the utility in the previous version before they renamed it to “phonegap”. I changed into the directory and ran the next command which gave the following error

$ cordova platform add ios
-bash: cordova: command not found

Changing it to “phonegap” doesn’t work either

$ phonegap platform add ios
[error] 'platform add ios' is not a phonegap command. See 'phonegap help'

But at least it gave some instruction on what to do. Following that I figured I has to run

$ phonegap local build ios

But alas, more errors

[phonegap] adding the iOS platform...
fs.js:413
 return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
 ^
Error: ENOENT, no such file or directory '/Users/thewheat/Dropbox/projects/ios/hello/www/config.xml'
 at Object.fs.openSync (fs.js:413:18)
 at Object.fs.readFileSync (fs.js:270:15)
 at Object.config_parser (/usr/local/lib/node_modules/phonegap/node_modules/cordova/src/config_parser.js:24:45)
 at Object.platform (/usr/local/lib/node_modules/phonegap/node_modules/cordova/src/platform.js:64:15)
 at LocalBuildCommand.module.exports.addPlatform (/usr/local/lib/node_modules/phonegap/lib/phonegap/local.build.js:153:13)
 at LocalBuildCommand.execute (/usr/local/lib/node_modules/phonegap/lib/phonegap/local.build.js:95:32)
 at LocalBuildCommand.run (/usr/local/lib/node_modules/phonegap/lib/phonegap/local.build.js:70:10)
 at Object.build (/usr/local/lib/node_modules/phonegap/lib/phonegap/util/command.js:28:25)
 at CLI.module.exports (/usr/local/lib/node_modules/phonegap/lib/cli/local.build.js:34:20)
 at CLI.module.exports [as argv] (/usr/local/lib/node_modules/phonegap/lib/cli/argv.js:66:17)

I figured, that I had to manually download the template project structure  (https://codeload.github.com/phonegap/phonegap-app-hello-world/tar.gz/3.0.0), extract it, and replace my project’s “www” folder with that in the template.

$ rm -rf www
$ cp -r ~/Downloads/phonegap-app-hello-world-3.0.0/www .

And now finally it compiles!

$ phonegap local build ios
[phonegap] adding the iOS platform...
[phonegap] compiling iOS...
[phonegap] successfully compiled iOS app

And to open it up in Xcode and finally run the app

$ open platforms/ios/HelloWorld.xcodeproj

Perhaps the node install was corrupted due to something on my computer? But broken documentation such as this really annoys me: a person trying to learn a new tool / library wants to test and play around with it, not debug broken installation guidelines.

(On a sidenote: at least there are some guidelines, there are projects that I’ve seen that don’t give a ‘quick start’ example and assumes you know how to use the tool, which is another peeve of mine)