Mobile/Symbian/NSPR

Overview

NSPR(NetScape Portable Runtime) is the most underlying component of the Mozilla platform. If we want to port FireFox or other Mozilla platform products onto a new OS, this is the very start line.

Symbian OS is the most widely used OS for smart phones worldwide. Because of its long evolution history, makers of Symbian OS had many concerns on mobile devices in old days when devices are quite different from desktop computers. For example their OS is run in ROM instead of hard disk, also their available memory is quite limited. So for quite a long time, developing applications or large mid-ware frameworks is a pain.

With the improvements of mobile devices' resource, they have less and less differences from a desktop/laptop PC. Since the second half of 2007, Nokia and Symbian provided their Symbian OS developers a framework called Open C, with help of "Open C" Symbian OS developers could treat the OS as a POSIX environment, although limitations exist.

Here we are porting NSPR to Symbian OS with "Open C", utilizing libc and libpthread. Determine where the boundaries are and marking them is our major work, also plus a load of build and test tricks.

Get updates

• Bug 432430 is the patch and discussion on NSPR for Symbian OS port.

• From Mozilla-Symbian project at GoogleCode you could find latest source of NSPR ports to Symbian OS before they get checked into Mozilla source tree.

• Check-in of NSPR in recent one month. Find what has been checked in already.

• Test cases report for NSPR on Symbian OS

• NSPR for Symbian OS Manually Test Result

Build

Discussion and patch about build system can be found at Bug 442706

Prerequisite

• MozillaBuild package. We use MSYS and nsinstall.exe in it.

• Nokia Carbide.c++ v1.3. We just need the compiler in it for building emulator targets.

• Nokia S60 SDK 3rd Edition (ActivePerl and JRE are prerequisites of S60 SDK)

• Nokia Open C Plugin for S60 SDK 3rd Edition

• Two environment variables should be set like this: one is for Symbian SDK path, the same as EPOCROOT except for different path separator and prefix, the other is path for ActivePerl.

SYMBIAN_SDK_PATH=/d/Symbian/9.1/S60_3rd_MR/
ACTIVE_PERL=/d/perl/bin/perl.exe

• If you also want to build emulator targets, additional three environment parameters for emulator compiler should be set, they are: MWCSYM2INCLUDES , MWSYM2LIBRARIES , MWSYM2LIBRARYFILES. Values for them could be retrieved from Carbide.C++ project properties.

Environment of mine

The environment that produces this patch is a bit of unique. I'm using Slackware Linux as my primary OS. And the build system is actually run in a VirtualBox VM whose guest OS is a Windows. This is because the compiler for emulator targets and many tools in Nokia S60 SDK are Windows only.

Furthermore, I have only 4GB virtual hard disk for my Windows VM as its "drive C", then the guest Windows and host Linux are connected with Samba. So inside the guest Windows there is a network mapped "drive D" connected to a host Linux path, for example /home/user/windowsdrive/. The advantage of doing so is that the VM guest OS and host OS can access all free disk space at the same time, and both of them could read/write all files under a specific path, though a little dangerous. My working copy of the mozilla source tree is located in that public path so I can do cvs and daily maintenance under Linux, and build/debug Symbian OS targets inside the guest Windows.

It sounds complicated, but it's really convenient. However, I don't have any recommendation that whether you should setup your Symbian development environment like me, or not. I just let you know this in case you run into any problem related with build environment.

Steps

The following description is based on NSPR build instruction.

# Get NSPR source by either cvs, then apply the patch
cvs -q -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co -r HEAD mozilla/nsprpub
# or get patched already sources from Mozilla-Symbian project at Google Code 
svn checkout https://mozilla-symbian.googlecode.com/svn/trunk/ mozilla

For Emulator target build:

# create a build directory
mkdir winscw.build
cd winscw.build
# run configure script
../mozilla/nsprpub/configure --target=arm-none-symbianelf --enable-symbian-target=WINSCW
# build the libraries
make
# build the test programs
cd pr/tests
make

For Device target build:

# create a build directory for emulator target
mkdir gcce.build
cd gcce.build
# run configure script
../mozilla/nsprpub/configure --target=arm-none-symbianelf --enable-symbian-target=GCCE --disable-debug
# build the libraries
make
# build the test programs
cd pr/tests
make

At this point, you have done building NSPR for Symbian OS.

Test

Though we can build NSPR as Symbian OS emulator binaries, yet the whole all test cases run is not suggested to be performed on emulator. The reason is some test cases can't run on emulator, and also emulator performance is quite different from a target device. So emulator build is only used to debug single problematic test case.

To run NSPR test cases on a target phone, we will prepare the device. Firstly, if the phone is not based on S60 3rd Edition Feature Pack 2, we have to install Open C libraries on the phone. Sending pips_nokia_1_3_SS.sis and stdioserver_s60_1_3_SS.SIS from the Open C plug-in installation path to the target device and installing them will do the job. For logging output during test cases run, we have to fix a configuration file. Get config.ini from NSPR for Symbian supporting files, and copy the file to the phone's C:\system\data\ path with any file browser tool, such as Y-Browser. Finally, use the file browser tool to create the folder C:\data\testlogs on the phone to store our logs from test cases run.

After transferring the ready to install run_nspr_tests_static.sisx to the test device, we could install it. Then there will be an icon show up in the phone's user interface named run_nspr_tests, launch this application just like any other application, all test cases will be launched one after another. You can say this run_nspr_test application is the runtests.sh on UNIX OS. On a Nokia N82 device, one single round of whole tests run will take about 30 minutes. When all tests finish, you could find each single test output and a summary nspr_test_log.log in phone's C:\data\testlogs.

Notes

The same as previous section Test, there is an important document Porting NSPR to Symbian Development Notes which will give you something valuable.

---

I will try to state points worthy your attention as many as I could.

• By now we can only build NSPR as static library and then link the .lib(around 80KB) into every single test case. So the final .sisx file with over 100 test case executables is over 7MB. The reason is that the GCCE compiler comes with S60 SDK can not produce correct DLL if Writable Static Data is used. Although there is a hope we could use a more recent GCCE release from CodeSourcery, yet there are other problems. So further investigation and workaround have to be carried out.

• Cause most output are written to stderr, but Symbian OS does not have the stderr output. We have to do some tricks to redirect stderr to stdout. In your Symbian SDK, for example D:\Symbian\9.1\S60_3rd_MR\Epoc32\include\stdapis, edit the stdio.h, change line 278 into the following lines:
  

#ifdef MOZ_STDERR_TO_STDOUT
#define stderr  (__stdout())
#else
#define stderr  (__stderr())
#endif

• The reason I put test cases logs in C:\Data is that on Windows you could *ONLY* access this phone directory with Nonkia PC Suite. With help of this tool, you will manipulates files on the testing device quite conveniently.

• If you are using Linux to communicate with the testing phone, my suggestion is KBluetooth and Krusader, just one obex://[00:11:22:AA:BB:CC]/C:/Data address will bring you to the phone (if your phone's bluetooth MAC address is 00:11:22:AA:BB:CC).

• In the first test case gethost, you have to use a SIM card with GPRS service available because it wants to communicate with DNS server and get IP address of a specific domain name. Also an IAP(Internet Access Point) manual selection is needed. So my intention of putting this test case as the first one is to leave you doing your other business without staring at the testing device after the first one.

• According to S60 3rd Edition: Application Development and practice, it is required to use ActivePerl as close as v5.6.1.635. Later or earlier version of ActivePerl has hidden incompatibilities with Symbian OS building purpose.

• As of May 27th, Open C plugin v1.3 got released. Open C plugin v1.3 now supports IPv6, but in the patch 331916 IPv6 support is not added into NSPR.

• More and more...

References and resources worth reading

Online documents related to NSPR for Symbian OS

• Unimplemented or Limited Functions
• Development notes
• Test cases report for NSPR on Symbian OS
• NSPR for Symbian OS Manually Test Result

NSPR port for Symbian OS supporting files

These files can be retrieved as attachment 331916 in bug 432430.

• config.ini - the file redirects stdout and stderr to C:\data\out.txt on testing device. If outputs are redirected to this file, it would be easier for you to check on the developing PC. Put this file ON THE PHONE 's C:\system\data.

• stdio.h - the file redirects stderr to stdio. Just put this file in your SDK include path, e.g. D:\Symbian\9.1\S60_3rd_MR\Epoc32\include\stdapis.

• moz_selfsign.cer/moz_selfsign.key - The self sign certificate/key pair files used to sign installation package file. Although self sign certificate/key pair files can be generated at will, yet these files have a valid date of 10 years because they are made by special tricks.

• run_temp_nspr_tests_static.pkg - An installation package definition file which will generate installation package file with only one single test case. Because we link NSPR as static library, more test case executables will waste a lot of disk space and the time we send the installation file into a testing device.

External resources

• Forum Nokia Symbian C++ Documentation
• How do I start programming for Symbian OS?
• S60 3rd Edition: Application Development
• Forum Nokia Symbian C++ KnowledgeBase
• About Symbian OS development
• Symbian Developer Library, a.k.a. the MSDN for Symbian
• Symbian Developer Network portal
• PIPS Is Posix On Symbian page, just regard this as libc
• My Blog, something about porting Mozilla platform onto Symbian OS