Building StatusNet Mobile from source

From StatusNet

Requirements

• Linux, Windows, or Mac system to build for Android
  • Android SDK (recommended to get current, 2.2 or later, packages; in theory should work running 1.6 or later systems, with Google APIs)
• Mac system to build for iPhone
  • XCode + iPhone SDK iPhone 3.2 or iOS 4.0
  • Note: testing on a real device and package distribution require setting up keys w/ Apple's dev program
• Windows system to build for BlackBerry (SDK not yet generally available)
• Appcelerator's Titanium Developer Studio package
  • This contains the open-source Titanium runtime libraries and build/packaging/debug interface.
  • Download and install the 1.4.0 Mobile SDK when prompted after launching the developer studio
    • Known problems on some 64-bit versions of Linux! Must remove some libs
  • Fetch or build a Titanium Mobile custom runtime build with fixes, optimizations, and upstream work ("1.4.1" partway towards 1.5.0).
    • (currently required!)
• git
• GNU make
• rsync

Fetching source

Grab the source from http://www.gitorious.org/statusnet-client per standard directions there

The latest in-progress code is in the 'master' branch:

 $ git clone git://gitorious.org/statusnet-client/statusnet-client.git

Importing project

Once you've set up Titanium Developer and checked out the source code, click the 'Import Project' button on the Titanium toolbar and select the 'StatusNet Mobile' directory inside your checkout.

Source layout

The StatusNet client is built using Appcelerator's open-source Titanium platform; its mobile variant provides a common JavaScript API over native controls for each supported platform, with more direct access to the system than a web browser provides.

Within the 'StatusNet Mobile' folder are various bits; most of the guts of the app will live under the 'Resources' folder:

• various images, etc
• platform-specific core startup code
• view/ subfolder with desktop-specific frontend code

Additionally, incomplete BlackBerry and Tablet (iPad) versions live in additional folders, which are not ready for use yet. To build the desktop clients see Building StatusNet Desktop from source.

Currently, some of the common code for the client lives in additional subprojects:

• StatusNet Desktop/Resources/model and StatusNet Desktop/Resources/lib contain common backend code
• heyQuery/Resources contains a wrapper for a tweaked version of jQuery's selector engine which is used by backend code when working with XML data. (You can build and run the heyQuery project separately to run its test suite. Note that some test cases are known to fail.)

These must be copied into the StatusNet Mobile folder tree before building; see notes below.

Graphics

Today's mobile devices run on a much wider range of display densities than we're used to in desktop and laptop computers. The runtime systems scale logical coordinates so that UI elements remain about the same size on each phone, but to keep them looking sharp many of the graphics and icons for the user interface need to be provided in at least three resolutions:

	circa 160 dpi: standard base resolution for classic iPhone, iPad, "medium-density" Android devices mentions_on.png (30x30) 1x scale factor: device coordinates are the same as logical display coordinates
	circa 240 dpi: "high-density" Android devices such as the Nexus 1 and Motorola Droid mentions_on240.png (45x45) 1.5x scale factor: make icons 50% larger on each side than the base version Currently these have to be manually selected and loaded; in the future the runtime will be able to choose them for us, but the will need to be renamed to match the naming scheme used.
	circa 320 dpi: iPhone 4 and iPod Touch with Retina Display mentions_on@2x.png (60x60) 2x scale factor: make icons twice as long on each side as the base version These files are automatically loaded by the runtime when used in main UI. (Not in web views!)

Building and running

Since we can't currently add custom build steps in Titanium, there's a Makefile to copy shared code into the StatusNet Mobile project's Resources folder:

 $ cd 'StatusNet Mobile'
 $ make

This will run the local rsync command to bring the local file trees up to date. When editing this code, be sure you're editing the originals, not the copies!

Let's make sure your SDK stuff is set up...

For Android:

• Make sure you have installed the Android SDK, updated all its files, and selected the path to it in your Titanium Developer user preferences.

For iPhone:

• Make sure you've selected "Titanium SDK 1.4.1" in the preferences of your StatusNet Mobile project, or else the build will fail (see first image to the right)
  

  

  Setting the Titanium SDK to successfully build the iPhone-version of StatusNet Mobile.
• When building and launching the StatusNet Mobile Client from "Titanium Developer" with the "Launch"-button, make sure you've selected the current iPhone SDK (currently 4.1), or-again-the build will fail. (see second image to the right)
  

  

  Setting the iPhone SDK to successfully build the iPhone-version of StatusNet Mobile.
• To run on a real device you'll need to jump through some hoops to set up your code signing keys. There should be some nice big buttons helping you do that when you get down to the build/run steps.
• Note that the current release of Titanium Developer may still have issues with the iOS 4 SDK -- search around on the net for the necessary tweaks or try their latest beta.
• if XCode is set to use a separate build directory by default, Titanium's builds won't work properly. Switch your preference back to using a build folder within the source project.

Select the app from the developer studio's sidebar and pick the 'Test & Package' tab; select whether to launch in the emulator or device and which platform to build for... then push 'Launch'!

Debugging

The developer studio app has a debug console when running apps in emulation, but it's a bit flaky currently; be prepared for a LOT of debug console noise, and you may not see any output for some error conditions. :(

Android:

• Beware: the emulator may take several minutes to boot, so avoid closing it!
  • (The emulator also runs slowly; CPU-bound code runs about 4x slower on my reasonably zippy laptop than it does on my Nexus 1.)
• Installing on a physical device has been a bit flaky for me. If it doesn't seem to be updating properly, try uninstalling the app first through Settings -> Applications -> Manage Applications.
• You can get additional debug output by attaching the Android debugger tool to the emulator or device; this will include Java exception backtraces and general system events, and is the only way to get debug output when running on a real device:
  • adb -d logcat # dumps live debug logs from USB-attached phone
  • adb -e logcat # dumps live debug logs from running emulator

iPhone:

• The iPhone simulator launches very quickly, so feel free to start/stop it with wild abandon!
  • On the other hand installing to a physical device is horribly slow, and goes through a slow iTunes sync.
• Be aware that the iPhone simulator runs native x86 code, not emulated ARM code, so may run much faster than an actual phone.
• When connected to a physical device, you can view live debug output from the Console tab after selecting the device in XCode's Organizer window. This will include the program's debug output as well as other log info from the device.
• With the latest SDKs installed, it may sometimes offer you iPhone SDK version 3.2 -- this will either not work, or launch in the iPad simulator, and is kind of funky. Either use the 3.1 SDK or the 4.0 SDK mode.
• By default, the iPhone 2/3 simulator is launched; with iOS 4 SDK, you can select iPhone 4 from the simulator's menu bar and it will relaunch in iPhone 4's high-resolution display mode.

Packaging

One of Appcelerator's extra goodies for the Titanium platform is hosted package/installer building and distribution. If you're not, you know, StatusNet Inc, it probably won't let you upload build packages under our package's id. :)

However you should be able to recreate the project under your account, with your own application ID, slap all the source code in, and be ready to go.

Android:

• If you have trouble with Titanium's 'Package' tab, just launch a local emulator or device build. This will create .apk builds which you can use. :)
• build/android/bin/app.apk will be signed with default debug key (?)
• build/android/bin/app-unsigned.apk is unsigned; you can then sign with your own private key for distribution.
  • You need to use a consistent signing key to keep updates running smoothly; if the key changes, users will need to manually uninstall and reinstall for future releases.
• packaging/sign-android is a shell script to do the signing, with some hardcoded paths to my dev workstation. ;) It'll be cleaned up in future to be more general.

iPhone:

• If you have trouble with Titanium's 'Package' tab, you can do the final build steps through XCode.
• Try a 'Run on device' which'll make sure it fills out the .xcodeproj
• Fire it up, you can work from there...
  • Follow the instructions in packaging/README for making signed Ad-Hoc or App Store distribution builds
  • packaging/build-iphone is a shell script to package up a flat .ipa file from your code-signed .app build