HOWTO develop Symbian apps using Mac OS X
Last major update, 2005/04/03
NB: I have not yet switched to Tiger because I'm in the middle of a development cycle. If you get it to work on Tiger, please let me know about it. I'll update this document once I upgrade.
Preamble
So you want to program for the millions of symbian cell phones using C++, but you just can't stand Windows. Or you don't want to shell out the $$$ for codewarrior. Or you feel more comfortable programming in a standard UNIX environment. Or you prefer using normal makefiles to the utterly hideous makmake build system. Or you just want to stick it to "the man" and try something different. Here I've tried to document the procedure I used to setup, install and program for Symbian on a Windows-free environment. Mac OS X is required.
Looking for Linux?
This used to be a Linux / OS X hybrid howto, but the whole point for me all along was to be working on OS X.... now it's finally possible to do that, so I've rewritten it to be OS X focused. However, the simple fact that you can do this on OS X means that you can do it on Linux as well, in fact more easily at this point. Many of the tips in this howto apply equally well to Linux. If you want to do Symbian dev on Linux, I recommend you use Rudolph König's sdk2unix which has become fairly straightforward I think. (I use it, in modified form, below.) There's also a complete resource list at the end of this HOWTO.
Changes
2005/04/02
Complete revision of the HOWTO to be specifically for building right on OS X. Which is what I always intended anyway, but it wasn't possible until this year.
2004/12/26
There have been some developments since the last major update that aren't included in this HOWTO yet.
- Rudolf Koenig has moved his sdk2unix files to his home page. The lastest version is newer than the one used in this HOWTO: version 1.4. For Series 60, it still uses the old GCC (gcc.539.src.zip) and the Series 60 SDK 1.2.
- The Symbian GCC Improvement Project has released a Symbian GCC compiler based on GCC 3.0. Reports indicate that the compiled code is substantially faster on the device, faster than what you get from Symbian Corp's own version that is. Speed and size improvements are in the range of 10%. It should be possible to substitute in something like gcc-3.0-psion-98r2 in for the official version when you reach that step in Rudolf's instructions.
Read this
A few notes before we begin.
Nokia-oriented but not Nokia-specific
This HOWTO will guide you through installing the Nokia Series 60 SDK. It just happens coincidentally that Series 60 is by far the most popular of all the Symbian flavours. However.... if you want to program for say UIQ or whatever you can still use most of these instructions, because the whole toolchain (including sdk2unix) is designed to work with any of the SDKs.
There is no emulator
There's no emulator available. I suppose it's no shock that the nokia emulator for windows doesn't run on Mac OS X. In fact, it doesn't run on wine either. Is that really such a bad thing? It depends. The "emulator" is actually NOT an emulator, it's a simulator. It doesn't actually emulate the ARM instruction set. Instead, they have effectively ported the entire Symbian / Series 60 API to windows. You build a windows binary file, which links against the ported libraries. So you can't actually take your ARM binaries and try them out in the emulator. There are some fairly major differences between the simulator and the real Symbian /Series 60 devices. One would be speed, but the most major is in memory management. There are however other more subtle differences.
It's fairly easy to set up logging to a file on the target device. So as long as you have had some practice debugging code with the use of extensive printf-style statements, it's possible to get along quite well (in my opinion) without the simulator or the debugger.
What's the OS environment?
I picked Mac OS X because my main computer is a Powerbook. I have a wireless connection which allows me to work wherever I wish. The OS X is 10.3.8.
Editing the code
I do most of my editing XCode, Apple's free IDE for Mac OS X. This is the IDE I am most familiar with. I'm sure that something like Eclipse would also be just fine, but this is what I use. I also do a fair bit of editing with command-line emacs.
Deploying builds
Here's another reason to use Mac OS X. OS X comes with very high-quality support for bluetooth that includes all of the various Series 60 phones. So, deploying is a simple matter of drag-and-drop onto the bluetooth icon. You transfer the app to the phone, it shows up as a message, the installer will launch automatically. Most symbian binaries are pretty small, so transfer times are minimal.
Another strategy is to copy the binary up to a web server that's publicly accessible. Then you can bookmark the location on your phone and download it "over the air" (called OTA). Again, the installer will kick in and install automatically. This will drive up your data bill though.
Now that we have those items out of the way, now we get to the installation.
Prep your local system
You should install the full suite of Apple's free developer tools.
You should also install fink in order to get various command-line tools that you'll need along the way. If you get to some step below that requires a command-line tool (e.g. bunzip2, recode) that you don't have, you need to install it from fink. (Some fink tools may only be available in the unstable tree, see the fink documentation for details on how to access it.)
You may also need X11, e.g. Apple's free X11. Without X11 you might have problems with missing libraries when you build gcc or something else.
Install gcc
Let's get started.
We're going to use the slightly old version of gcc that Symbian still amazingly uses. It's called "gcc539". We're going to use a version that's been modified by Alfred E. Heggestad.
wget http://symbianos.org/download/gcc-539-2aeh-source.tar.bz2
bunzip2 gcc-539-2aeh-source.tar.bz2
tar -xvf gcc-539-2aeh-source.tar
This will create a directory "src" with the gcc code in it. Now get a patch by Andre Howe. (You're going to have to patch code quite a few times in this HOWTO. Hopefully the package maintainers will integrate these fixes into their code sooner or later and this won't be necessary any more.)
wget http://www.symbianos.org/~andreh/diff539
patch -p0 < diff539
You now have a patched src directory. Next you have to pick a destination
directory. This is where gcc will be installed. I recommend
/usr/local/symbian (you'll need root access).
Create the destination dir and then build gcc.
sudo mkdir /usr/local/symbian
mkdir obj
cd obj
sh ../src/configure --prefix=/usr/local/symbian \
--exec-prefix=/usr/local/symbian --target=arm-epoc-pe
make
Well, despite all the patches, you're still going to get an error from src/libiberty/strerror.c. So hand apply the following change (basically just comment out lines 465 and 466).
--- ../src/libiberty/strerror.c Fri Apr 1 01:00:01 2005
+++ ../src/libiberty/strerror.c.orig Fri Apr 1 00:59:21 2005
@@ -462,8 +462,8 @@
#else
-//extern int sys_nerr;
-//extern char *sys_errlist[];
+extern int sys_nerr;
+extern char *sys_errlist[];
#endif
...and make again. It's going to take a little while.
Finally, install it (requires sudo for root access).
But first, fix a stupid permissions problem that also needs to be fixed...
chmod u+x ../src/dejagnu/mkinstalldirs \
../src/tcl/unix/mkLinks ../src/texinfo/mkinstalldirs \
../src/tk/unix/mkLinks ../src/expect/mkinstalldirs
sudo make install
Now symbian gcc is installed.
Install makesis, rcomp, bmconv, petran
These are all essential tools to build symbian apps. The story is, that Symbian kindly open sourced a number of tools in order to make it easier for people like us to play. The packaged SDKs however only come with compiled EXEs for windows. So we just have to get the source and build them ourselves.
This is pretty straightforward. Get the source, unpack, make, test, install.
makesis
wget http://symbianos.org/~andreh/makesis-2.0.0.tar.gz
tar -xvzf makesis-2.0.0.tar.gz
cd makesis-2.0.0
make
make regtest
sudo cp src/makesis /usr/local/symbian/bin/
rcomp
wget http://symbianos.org/~andreh/rcomp-7.0.1.tar.gz
tar -xvzf rcomp-7.0.1.tar.gz
cd rcomp-7.0.1/
make
make regtest
At this point you might hit a snag, a lot of test failures. I applied this patch, from here, but it still failed all kinds of tests. Oh well. It seems to work anyway.
sudo cp src/rcomp /usr/local/symbian/bin/
bmconv
wget http://symbianos.org/~andreh/bmconv-1.1.0-2.tar.gz
tar -xvzf bmconv-1.1.0-2.tar.gz
cd bmconv-1.1.0-2/
make
make regtest
sudo cp src/bmconv /usr/local/bin/
petran
wget http://symbianos.org/~andreh/petran-1.1.0.tar.gz
tar -xvzf petran-1.1.0.tar.gz
cd petran-1.1.0/
make
make regtest
sudo cp petran/petran e32uid/uidcrc /usr/local/symbian/bin/
Install sdk2unix
sdk2unix is a tool by Rudolf König. It replaces the idiotic makmake system that Symbian uses with a sensible and normal makefile system. And, it does a whole lot of conversion on the SDK to make it work sensibly in a Unixy kind of way. It's really good stuff.
Rudi provides his own installation instructions which are fine for Linux but you can't use them for OS X (at the moment, anyway) so ignore them. Everything will be explained here. Note that sdk2unix supports other SDKs too, like UIQ, etc, not just Series 60.
Anyway, download and unpack it.
wget http://www.koeniglich.de/packages/sdk2unix-1.5.tar.gz
tar -xvzf sdk2unix-1.5.tar.gz
Now copy some of its useful stuff to where we installed the compiler.
cd sdk2unix-1.5
sudo cp -rp data/gcc539/makerules /usr/local/symbian/lib
sudo cp data/gcc539/specs \
/usr/local/symbian/lib/gcc-lib/arm-epoc-pe/2.9-psion-98r2/specs
sudo cp bin/xmakesis.pl /usr/local/symbian/bin
Create some links...
cd /usr/local/symbian/bin/
sudo ln -s \
../lib/gcc-lib/arm-epoc-pe/2.9-psion-98r2/cpp arm-epoc-pe-cpp
sudo ln -s arm-epoc-pe-as as
genaif
genaif (a special sdk2unix tool) requires a patch to make it work on OS X. You need to get the genaif patch from ... mailing list archives (we're on the bleeding edge here people) ... and copy and paste it into a file called "patch.txt". When you build genaif, ignore the warnings about PutLong etc.
cd genaif/
patch -p0 < patch.txt
cc -o genaif genaif.c
sudo mv genaif /usr/local/symbian/bin/
Install the Software Developer's Kit
The SDK contains the essential tools and libraries to develop for whatever phone you target. All of the important Symbian SDKs can be found at Symbian's site.
Download Series 60 SDK 2.1 for Symbian OS, Nokia Edition (you have to use the web interface...). It should come out as S60_SDK_2_1_NET.zip, 115.9 MB. Don't unzip it.
Decide where you want to store the final SDK. I personally use ~/sandbox/symbian/SDK_21 ... this could be useful later on if you want to have multiple SDKs installed.
Meanwhile, I'll assume that you've downloaded the zip file to ~/Desktop. Don't unzip it. That will be done for you automatically by code that I wrote that Rudi put into sdk2unix. Now invoke sdk2unix's magic install command, with the location of the SDK archive, where you want it to go, and the location of the symbian gcc you installed before.
cd sdk2unix-1.5
bin/install_series60_sdk_21 \
~/Desktop/S60_SDK_2_1_NET.zip \
~/sandbox/symbian/S60_21 \
/usr/local/symbian/bin/arm-epoc-pe-gcc
And that's it. You're done installing the SDK. Let's build something.
Build a S60 example
sdk2unix installs makefiles into several of the series60ex directories. You can find them using the Finder or the find command.
cd S60_21/
find . -name makefile
I assume you are familiar with makefiles. If not you might as well start with the GNU Make page.
Fix core makefiles
There's a set of core makefiles that we copied into /usr/local/symbian/lib/makerules. You'll need to hand-apply the following patch to epoc.general to make it work, since we deviated a little bit from the default sdk2unix install. Obviously SDKLOC should be where you put the SDK on your system.
--- epoc.general.orig Fri Apr 1 03:06:47 2005
+++ epoc.general Fri Apr 1 21:01:32 2005
@@ -8,10 +8,11 @@
GA = genaif
PKGVERS = 1,0
-EPOCTRGREL = $(EPOC)/Release/armi/urel
+SDKLOC = /Volumes/MacintoshHD/Users/woodside/sandbox/symbian/S60_21
+EPOCTRGREL = $(SDKLOC)/Release/armi/urel
-CPPFLAGS = -I$(EPOC)/include
-CFLAGS = -I$(EPOC)/include -I$(EPOC)/include/libc
+CPPFLAGS = -I$(SDKLOC)/include
+CFLAGS = -I$(SDKLOC)/include -I$(SDKLOC)/include/libc
%.o: %.c
@echo "[CC ] $*"
(Note: this is actually a little bit messed up if you want to actually separate the SDK and the gcc installation properly. But I haven't quite figured out how to do that yet.)
Recode the example files
For some reason sdk2unix didn't recode the examples. You need to recode them from DOS to UNIX formats. Mainly this affects the line endings. If you don't do this, you're going to get loads of errors from rcomp.
cd S60_21/series60ex/
find . -type f -print | xargs recode -f dos..latin1
Fix example makefile
Now we're going to build an example, specifically the series 60 form example.
It's in series60ex/form.
In the src directory,
there's a makefile, installed by sdk2unix, but it needs to be fixed a bit.
(These are flaws from sdk2unix.)
NB - You must also change the first line to reflect your own path to the symbian libraries e.g. /usr/local/symbian.
--- makefile.orig Fri Apr 1 21:06:23 2005
+++ makefile Sat Apr 2 21:15:44 2005
@@ -8,27 +8,26 @@
$(EPOCTRGREL)/cone.lib \
$(EPOCTRGREL)/eikcore.lib \
$(EPOCTRGREL)/eikcoctl.lib \
- $(EPOCTRGREL)/eikctl.lib \
- $(EPOCTRGREL)/eikdlg.lib \
$(EPOCTRGREL)/avkon.lib \
- $(EPOCTRGREL)/eikdlg.lib
-
+ $(EPOCTRGREL)/eikdlg.lib \
+ $(EPOCTRGREL)/eikctl.lib
NAME=aknexform
OBJECTS= aknexformapp.o aknexformappui.o aknexformcontainer.o\
- aknexformdocument.o aknexformsaveform.o aknexformsavetestform.o\
+ aknexformdocument.o aknexformsaveform.o\
aknexformview.o
TARGET=$(NAME).app
PKGVERS=1,1
+PKG_ADDON='(0x101F6F88), 0, 0, 0, {"Series60ProductID"}'
PKGFILES=$(NAME).app $(NAME).aif $(NAME).rsc
-U1 = 1000007a
+U1 = 10000079
U2 = 100039ce
U3 = 10005C33
-CFLAGS = -O -DNDEBUG -I. -I../inc -DUID3=0x$(U3) -D_QUARTZ -D_EPOC32_61
+CFLAGS += -O -DNDEBUG -I. -I../inc -DUID3=0x$(U3) -D_QUARTZ -D_EPOC32_61
CPPFLAGS += -D_QUARTZ -D_EPOC32_61 -I../inc
Build
When you've applied those changes, now make sure you are in the src directory, and type make.
cd src
make
Include files and case sensitivity
You might get some errors about missing include files.
Many of the source files in the examples have #include statements that use the wrong case for include files. They will include upper case letters but sdk2unix converted everything to lower case. The DOS/Windows filessystem is case insensitive but every UNIX including Linux and OS X is case sensitive.
Edit the source files and lowercase the names of the includes. When you're done and everything works you should get this result from make.
[CPP ] aknexform
[RCOMP ] aknexform
[C++ ] aknexformapp
[C++ ] aknexformappui
[C++ ] aknexformcontainer
[C++ ] aknexformdocument
[C++ ] aknexformsaveform
[C++ ] aknexformview
[DLL1 ] aknexform
[LD1 ] aknexform
[DLL2 ] aknexform
[LD2 ] aknexform
[PETRAN] aknexform
PETRAN - PE file preprocessor V01.00 (Build 175)
Copyright (c) 1996-2001 Symbian Ltd.
NumberOfFunctions[1]
echo "mbmfile=icon.mbm" >> aknexform.aifspec
echo "ELangEnglish=aknexform" >> aknexform.aifspec
[GENAIF] aknexform
[PKGBLD] aknexform
[MAKSIS] aknexform
Processing aknexform.pkg...
Created aknexform.sis
rm aknexform.exp aknexform.def1 aknexform.ex2 aknexform.rpp aknexform.bas
Install on the phone with bluetooth
Assuming you've already paired the phone, fire up the Bluetooth File Exchange app and copy aknexform.sis to the phone. Install and run it. It will show off a bunch of different kinds of forms that S60 supports.
Adapting the makefile to your own app
You can basically copy the form makefile to your own app. It should be fairly self-explanatory how to change it. One gotcha is that there's a rule in it:
aknexformapp.o: $(NAME).rsc
You have to change that to:
yourownapp.o: $(NAME).rsc
General tips
On-target logging
There is no on-target debugger so you'll have to use some file of file logging to find out what your program is doing. Get yourself a copy of the free and excellent FExplorer file utility for symbian.
To log to a file, you can use the RFileLogger API. Something like this:
RFileLogger::Write(LOG_DIR, LOG_NAME, LOG_MODE, msg);
NewLC's Creating log files has more details.
Display extended error codes on the phone
You'll definitely need to read this article as well: Display the extended panic code in Emulator or Device.
Helpful resources
Discussion groups
NewLC has excellent articles and forums.
Forum Nokia discussion area is another excellent resource you can search with their advanced search function (it's not indexed in google...).
publicnews.symbiandevnet.com can be helpful for highly technical questions not specifically oriented towards Series 60.
SymbianOS.org
Open Source programs for SymbianOS has code, mailing lists, online forums, a wiki, etc. for open source development for and on Symbian.
Symbian GCC Improvement Project
You might also want to experiment with gcc's from the Symbian GCC Improvement Project which are newer but I can't guarantee they'll work.
gnupoc
There is more of a straight port of Symbian tools for Linux called GnuPoc. (It's a play on the hideous name EPOC which was what Symbian was called back in the 90s.) The gnupoc project has generated some great ports of various symbian tools to Linux and OS X. However, as a complete system, I tried out gnupoc and found it unsatisfying. Just like on windows, it uses makmake and that's just a mess. However, they claim to have an emulator for some of the UIQ phones so if you're developing for those phones you might want to check it out.
Help and feedback
Hopefully everything will work! If it doesn't, feel free to email me. I'll try to help.