Mobile/Symbian/NSPR

From MozillaWiki
< Mobile‎ | Symbian
Revision as of 03:03, 12 June 2008 by Kcome (talk | contribs) (→‎Test)
Jump to navigation Jump to search

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 a good start.

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.

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

Build

Prerequisite

  • Get familiar with NSPR and Mozilla Platform.
  • Get familiar with Symbian OS and its characteristics. Know how to build helloworld on Symbian OS, of course setting up build tool chain. Own a Nokia S60 smart phone device is recommended.

In case you are new to Symbian OS application development, please read these resources.

Environment of mine

The environment that produces this patch is a little different from prerequisites listed above. I'm using Slackware Linux as my primary OS. This Slackware is based on V12.0 and runs a self customized 2.6.24.4 kernel. In my Slackware I set up a MS Windows virtual machine with SUN VirtualBox. What's more unique is that I have only 4GB virtual hard disk for my MS Windows VM as its "drive C", then I connect the guest Windows OS and host Linux with Samba. So inside the guest Windows OS 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 sometimes a little dangerous. My working copy of the mozilla source tree is located in the public path so I can do cvs and daily maintenance under Linux, and build/debug Symbian OS executables inside the guest Windows OS.

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 want you to know this in case you feel strange about something below.

Steps

Now let's get the meat.

  • Get Mozilla source tree, by either CVS or FTP download.
  • Apply the patch against the tree, at mozilla/nsprpub/.
  • Make sure Symbian development tool chain are ready. Run some helloword.
  • Assume your Mozilla source tree is located at D:\mozilla, and you have downloaded and installed S60 SDK 3rd Edition Maintenance Release. Launch your Carbide.C++, and do following steps:
    • From menu, choose File » Import » Symbian OS Bld.inf file
    • type D:\mozilla\nsprpub\build\symbian\bld.inf
    • Select S60_3rd_MR and all two child nodes
    • Two Next to finish
  • In NSPR tests, most output are written to stderr, but Symbian OS just ignores the stderr output. We have to do some tricks. 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
  • In your Carbide.C++, now you can choose Project » Build Project from menu to compile and link NSPR for Symbian OS.
  • By default, the IDE builds binaries for Emulator(WINS). We could build binaries for device by select Project » Build Configurations » Set Active » Phone Release from menu.
  • If there is no error after building the Phone Release project configuration, it's time to generate target device installation package. Select Project » Properties from menu, select Carbide.c++ » Carbide Build Configurations, click Add in tab SIS Builder to select our .pkg file. Probably it is located at D:\mozilla\nsprpub\build\symbian\sis\run_nspr_tests_static.pkg. Then we have to select Sign sis file with certificate/key pair, and locate the certificate/key pair files from NSPR for Symbian supporting files.
  • Do the Project » Build Project again from menu bar, you will finally see the line in Console output.
... ...
... ...
***SIS Creation Complete

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

Test

Before describing how to test NSPR on Symbian OS, you could get current test status from two important documents. They are

Although we can build NSPR for Symbian OS as emulator binaries, yet the 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 a phone utility called Y-Browser. Finally, use Y-Browser 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 which are generated in last step Build 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.

  • 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 intension 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.

References and resources worth reading

NSPR port for Symbian OS supporting files

These files can be retrieved as attachment 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 has 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

Retrieved from "https://dev.wikimo.nonprod.webservices.mozgcp.net/index.php?title=Mobile/Symbian/NSPR&oldid=96465"