How to build WordPress for iOS (2015)

WordPress-LogoThe WordPress for iOS project has changed and grown over the years. While it’s still Open Source, it’s not as easy as “checkout and deploy” anymore. You may encounter several pitfalls along the way.

At the time of writing, the current version of WordPress for iOS is 5.7, with 5.8 just around the corner. In this article I’ll show you how to build the project and deploy it on your own devices.

Where to get the source code

WordPress for iOS is developed by a team of decentralised folks, most of them working on it full time. The project is in constant change and the source code can be found on GitHub:

The version that’s currently on the App Store can usually be found in the master branch, or as a release tag. Those are stable versions.

The develop branch contains what’s currently being worked on and will at some point become the next version when the code freezes. Needless to say, it’s experimental until it’s released and hence may not always be stable.

Pick a release and download it, either as a standalone zip, or fork the whole project and create your own changes in a new branch. If you intend to contribute back to the project then the latter approach is the right one, however it comes with the overhead of years of work – so if all you want to do is make a few personal changes, downloading a standalone tag is a lot quicker, and you won’t be notified of the ongoing changes to the project.

No matter how you check out the project, make sure there’s no SPACE in any of the root or parent folders, otherwise there’s a big chance of unexplained build errors (trust me, I’ve been there).

If you were to open the project in Xcode now you’ll probably notice a lot of warnings and errors. We’ll address how to fix those below.

Dependencies

Back in the day, WordPress was a rather large standalone project. As it grew and pulled in other libraries over time, it was no longer a feasible endeavour for the team.

In 2014 the decision was made to split the project into smaller chunks that could be worked on independently, and also be used in part for other projects (including your own): for example, there’s the WordPress Editor, or the WordPress API, and many other components that make up WordPress for iOS – as well as third party libraries such as AFNetworking.

In order to resolve those dependencies, WordPress uses the legendary Cocoapods. Install it by launching a Terminal session and type the following:

sudo gem install cocoapods

It’ll take a moment for this to finish and you’ll be prompted for your Mac’s admin password.

If this step is giving you any agony under El Capitan, say thanks to the wonderful new OS X feature known as System Integrity Protection. It’s known to interfere with the Cocoapods installation among other things. In essence it won’t allow the root user to do its job. If you’re having any trouble, disable System Integrity Protection and try again (I’ve explained how to do that here).

Once Cocoapods is installed, we need to resolve the dependencies WordPress needs to build the project.

With your Terminal session still open, change into your WordPress folder. In case you’re new to this, type cd followed by a SPACE, then drag the WordPress folder from a Finder window into the Terminal session and hit return. That should do it.

Now resolve the dependencies with

pod install

Grab a coffee – this could take some time.

Opening the WordPress Project in Xcode

At the time of writing, WordPress for iOS requires Xcode 7 or higher. Xcode 7.1.1 seems to works fine with WordPress version 5.8. Obviously this changes as fast as Apple churn out new versions of Xcode, so check the readme on GitHub. The folks are pretty good at updating critical changes right there on the front page.

To open WordPress in Xcode, look for an Xcode Workspace file (.xcworkspace). Note that this is something different to the usual Xcode Project file (.xccodeproj): a Workspace can contain more than one Xcode project, and all those independent projects can then be built in the same folder.

On the left hand side, the correct target should be picked already (it’s called WordPress, with a blue logo). If you don’t see the list of targets, click on that little square icon next to General, it will expand that list for you.

Screen Shot 2015-12-07 at 09.40.12

Try building the app by hitting CMD+B. Apart from a few warnings, there should be no build errors.

Now try to run the app on the simulator. This should work fine too, once you’ve selected your own team. If you’ve made it this far, well done! Let’s see how we can deploy WordPress to a real device next.

Deploying WordPress to a real device

Trying to deploy WordPress on your iOS device will likely result in a message like this:

Screen Shot 2015-12-07 at 10.02.00

Even if you select the super friendly option to “fix the issue”, all you’ll get is another window like this:

Screen Shot 2015-12-07 at 10.02.25

This particular warning has to do with the fact that Xcode cannot enable capabilities on automatic provisioning profiles. There’s an easy workaround: switch off capabilities that we clearly don’t need for this version of WordPress.

To do this, select the WordPress target and select Capabilities at the top. Go through the list and notice that the following items are enabled:

  • Maps
  • Keychain Sharing
  • Background Modes
  • App Groups

Disable all except for Background Modes. Now select the Today Widget target and disable the same capabilities there too.

Deploy to your device again and be greeted with success!

Give your own WordPress a separate Bundle ID

If you do not intend to contribute back to the project and would just like to run an amended version of WordPress on your device, you may want to run it side by side with the App Store version. In this case you must change the bundle identifier. This will allow both versions to exist on the same device.

For example, change org.wordpress to org.wordpress.you.

Likewise, you must change the bundle ID of the (annoying) Today Widget to have the same prefix. To do this, select the Today Widget target, and change org.wordpress.WordPressTodayWidget to org.wordpress.you.WordPressTodayWidget.

Alternatively, feel free to remove the Today Widget target altogether.

On this note, both apps are now called WordPress and will have the same logo on the springboard. To tell them apart, change the Bundle Display Name from ${PRODUCT_NAME}  to something else (like “My WordPress). You can do that by selecting the WordPress target, then head to Info at the top.

Screen Shot 2015-12-07 at 10.14.32

Logging in to WordPress websites

At this point you can log in to any self-hosted WordPress site with your URL and credentials. For most of us this is probably going to be enough.

If you want to log in to your WordPress.com account however, you’ll notice that despite correct credentials, it’s not going to work. There’s a little extra setup that we need to do first:

  • head over to developer.wordpress.com and create an account (remember the credentials)
  • create a new app and choose Web Client as the type (do not choose Native Client)
  • under My Applications – Manage Applications – OAuth Information, make a note of your Client ID and Client Secret

WordPress for iOS will use these two items to authenticate you with WordPress.com. The project does this by using a file called .wpcom_app_credentials that resides in your Mac’s home folder. This file does not exist by default, so go ahead and create it (either via Terminal or TextEdit, whichever you prefer).

Populate the file with the following values:

WPCOM_APP_ID=
WPCOM_APP_SECRET=
POCKET_CONSUMER_KEY=
MIXPANEL_DEVELOPMENT_API_TOKEN=
MIXPANEL_PRODUCTION_API_TOKEN=
CRASHLYTICS_API_KEY=
GOOGLE_PLUS_CLIENT_ID=
HOCKEYAPP_APP_ID=
HELPSHIFT_API_KEY=
HELPSHIFT_DOMAIN_NAME=
HELPSHIFT_APP_ID=
TAPLYTICS_API_KEY=

Add your own Client ID and Client Secret after the equals sign as WPCOM_APP_ID and WPCOM_APP_SECRET respectively, then save the file.

Because each home folder on our Macs is different, verify that you’ve got the correct path: in Xcode, select the WordPress target, head over to Build Settings and scroll to the very bottom. Under User Defined, you’ll find a section called WP_CONFIG. The full path to the file will be displayed under Debug, Distribution and Release (mine for example is /Users/versluis/.wpcom_app_credentials).

Screen Shot 2015-12-07 at 15.19.07

With all this setup, deploy the app to your device again and login to WordPress.com using the credentials you’ve used for your WordPress developer account. If you have any site setup on this account, you’ll see them all in the app, together with any connected self-hosted sites.

Congratulations if you’ve made it this far!

It was a tough and rocky ride, but you’ve made it – well done! Now go and play with the WordPress code: there’s tons to learn and explore, amend, test, tweak and play with. Who knows, maybe you can even improve the project and offer your bug fixes and new features as pull requests.

Further Reading





Leave a Reply