|
|
| (40 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| = Overview =
| | {{Outdated}} |
|
| |
|
| [http://www.mozilla.org/projects/nspr/ NSPR(NetScape Portable Runtime)] is the most underlying component of the [http://blog.mozilla.com/schrep/2007/05/16/mozilla-platform/ Mozilla platform]. If we want to port FireFox or other Mozilla platform products onto a new OS, this is a good start.
| | == What's Up == |
|
| |
|
| [http://www.symbian.com Symbian OS] is the most widely used OS for smart phones worldwide. Because of its [http://en.wikipedia.org/wiki/Symbian_OS#History 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.
| | In short: |
| | Building NSPR for Symbian. |
|
| |
|
| 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 [http://www.forum.nokia.com/main/resources/technologies/open_c/index.html Open C], with help of "Open C" Symbian OS developers could treat the OS as a POSIX environment, although limitations exist.
| | Complete one: |
| | Building NSPR with source from http://mozilla-symbian.googlecode.com for Symbian OS/S60 3rd Edition FP1 platform by using gnu-make/msys. |
|
| |
|
| Here we are porting NSPR to Symbian OS with "Open C", utilizing <tt>libc</tt> and <tt>libpthread</tt>. Determine where the boundaries are and marking them is our major work, also plus a load of build and test tricks.
| |
|
| |
|
| [https://bugzilla.mozilla.org/show_bug.cgi?id=432430 Bug 432430] is the patch and discussion on NSPR for Symbian OS port.
| | == Prerequisites == |
|
| |
|
| = Build = | | * Windows XP or compatible |
| | * [http://www.forum.nokia.com/info/sw.nokia.com/id/4a7149a5-95a5-4726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html S60 SDK 3rd Edition FP1] |
| | * Prerequisites for S60 SDK: [http://downloads.activestate.com/ActivePerl/Windows/5.6/ActivePerl-5.6.1.638-MSWin32-x86.msi Active Perl] '''EXACTLY V5.6.1.638, no earlier no later''' and [http://java.sun.com/ JRE v1.5] (JRE is not required) |
| | * [http://www.forum.nokia.com/info/sw.nokia.com/id/91d89929-fb8c-4d66-bea0-227e42df9053/Open_C_SDK_Plug-In.html Open C Plugin for S60 SDK] |
| | * [http://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-1.3.exe Mozilla-build v1.3] |
| | * [http://downloads.sourceforge.net/mingw/MinGW-5.1.4.exe?modtime=1209244789&big_mirror=1 MINGW latest] |
| | ** Make sure to select "g++" during the install process |
|
| |
|
| == Prerequisite == | | == Procedures == |
|
| |
|
| * Get familiar with NSPR and Mozilla Platform. | | * Install all prerequisites, I recommend installing everything on Drive C, default path. |
| | * Add paths to environment variable $PATH, some of them are added by tools installation: |
| | ** <tt>c:\mingw\bin</tt> ('''MUST''' be the first, or at least earlier than any Symbian build tool chain related path) |
| | ** <tt>c:\program files\csl arm toolchain\bin</tt> (this should be added by GCCE tools installation) |
| | ** <tt>c:\symbian\9.2\s60_3rd_fp1\epoc32\tools</tt> ('''MUST''' place this earlier than "<tt>c:\program files\common\symbian\tools</tt>" which is added by SDK installation) |
| | ** <tt>c:\mozilla-build\svn-win32-1.4.2\bin</tt> |
| | ** <tt>c:\mozilla-build\moztools\bin</tt> |
| | * Add environment variables: |
| | SYMBIAN_SDK_PATH = /c/symbian/9.2/S60_3rd_FP1/ |
| | ACTIVE_PERL = /c/perl/bin/perl.exe |
| | CC_INSTALL_PATH = /c/program\ files/CSL\ ARM\ Toolchain/ |
| | * Fix a [http://wiki.forum.nokia.com/index.php/KIS001022_-_Open_C:_Initializer_element_is_not_constant_error_on_GCCE_platform header file bug]: in <tt>$EPOCROOT/Epoc32/include/e32def.h</tt>, change: |
| | static const char* const KSuppressPlatSecDiagnostic = |
| | KSuppressPlatSecDiagnosticMagicValue; |
| | into |
| | #if defined(__cplusplus) |
| | static const char* const KSuppressPlatSecDiagnostic = |
| | KSuppressPlatSecDiagnosticMagicValue; |
| | #endif |
| | * Deal with header files |
| | c: |
| | cd \symbian\9.2\s60_3rd_fp1\epoc32\include |
| | move prtypes.h prtypes.h.orig |
| | cd variant |
| | copy Symbian_OS_v9.2.hrh Symbian_OS.hrh |
|
| |
|
| * Get familiar with Symbian OS and its characteristics. Know how to [http://www.symbian.com/developer/techlib/v9.3docs/doc_source/guide/cpp-intro/HandsOnCpp.html#OSGuide%2eHandsOnCpp build <tt>helloworld</tt>] on Symbian OS, of course setting up build tool chain. Own a [http://www.forum.nokia.com/devices/matrix_s60_3ed_1.html Nokia S60 smart phone] device is recommended. | | * Checkout source from google code <br> |
| | svn checkout http://mozilla-symbian.googlecode.com/svn/trunk/ mozilla-symbian |
| | * Start msys by invoking <tt>c:\mozilla-build\msys\msys.bat</tt>, assuming your source is checked out at <tt>c:\mozilla-symbian</tt> then: |
|
| |
|
| * Symbian OS application build tool chain includes:
| | For device(GCCE) build: |
| *# Microsoft Windows XP
| | cd /c/ |
| *# Nokia [http://www.forum.nokia.com/main/resources/tools_and_sdks/carbide_cpp/index.html Carbide.c++] v1.3 as IDE
| | mkdir gobj |
| *# Nokia [http://www.forum.nokia.com/info/sw.nokia.com/id/4a7149a5-95a5-4726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html S60 SDK] 3rd Edition ([http://www.activestate.com/Products/activeperl/index.mhtml ActivePerl] and [http://www.java.com/en/download/manual.jsp JRE] are prerequisites of S60 SDK)
| | cd gobj |
| *# Nokia [http://www.forum.nokia.com/info/sw.nokia.com/id/91d89929-fb8c-4d66-bea0-227e42df9053/Open_C_SDK_Plug-In.html Open C Plugin] for S60 SDK 3rd Edition
| | ../mozilla-symbian/nsprpub/configure --target=arm-none-symbianelf |
| | --enable-symbian-target=GCCE --disable-debug |
| | make |
| | cd pr/tests |
| | make |
|
| |
|
| * [https://bugzilla.mozilla.org/attachment.cgi?id=324584 Patch 324584], <tt>nspr port for Symbian OS, with testcases run</tt>
| | For emulator(WINSCW) build: |
| | cd /c/ |
| | mkdir wobj |
| | cd wobj |
| | ../mozilla-symbian/nsprpub/configure --target=arm-none-symbianelf |
| | --enable-symbian-target=WINSCW |
| | make |
| | cd pr/tests |
| | make |
|
| |
|
| ----
| |
|
| |
|
| In case you are new to Symbian OS and development, please read these [http://wiki.mozilla.org/Mobile/Symbian/NSPR#Resources_Worth_Reading.2FReferencing resources].
| | == More == |
|
| |
|
| === Environment of mine ===
| | The procedures above are also verified on S60 SDK 3rd Edition MR. |
| | |
| The environment that produces this patch is a little different from prerequisites listed above. I'm using [http://www.slackware.org 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 [http://www.virtualbox.org 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 [http://www.samba.org Samba]. So inside the guest Windows OS there is a network mapped "drive D" connected to a host Linux path, for example <tt>/home/user/windowsdrive/</tt>. | |
| | |
| 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 [http://developer.mozilla.org/en/docs/Mozilla_Source_Code_Via_CVS CVS] or [http://developer.mozilla.org/en/docs/Download_Mozilla_Source_Code FTP download].
| |
| * Apply the [https://bugzilla.mozilla.org/attachment.cgi?id=324584 patch] against the tree, at <tt>mozilla/nsprpub/</tt>.
| |
| * Make sure Symbian development tool chain are ready. Run some <tt>helloword</tt>.
| |
| * Assume your Mozilla source tree is located at <tt>D:\mozilla</tt>, 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 <tt>D:\mozilla\nsprpub\build\symbian\bld.inf</tt>
| |
| ** Select <tt>S60_3rd_MR</tt> and all two child nodes
| |
| ** Two '''''Next''''' to finish
| |
| * In NSPR tests, most output are written to <tt>stderr</tt>, but Symbian OS just ignores the <tt>stderr</tt> output. We have to do some tricks. In your Symbian SDK, for example <tt>D:\Symbian\9.1\S60_3rd_MR\Epoc32\include\stdapis</tt>, edit the <tt>stdio.h</tt>, change line 278 into the following lines:<br/>
| |
| #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 is building 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 <tt>.pkg</tt> file. Probably it is located at <tt>D:\mozilla\nsprpub\build\symbian\sis\run_nspr_tests_static.pkg</tt>. Then we have to select '''Sign sis file with certificate/key pair''', and locate the certificate/key pair files from [https://bugzilla.mozilla.org/attachment.cgi?id=324627 NSPR for Symbian supporting files].
| |
| * Do the '''Project » Build Project''' again from menu bar, you will finally see the line <br>"''***SIS Creation Complete''"<br> in Console output. 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
| |
| | |
| * [http://spreadsheets.google.com/pub?key=puHMGxziDYnOk8BeukovcSA Test cases report for NSPR on Symbian OS]
| |
| | |
| * [http://spreadsheets.google.com/pub?key=puHMGxziDYnMi1x6iShmfQw NSPR for Symbian OS Manually Test Result]
| |
| | |
| ----
| |
| | |
| 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 [http://www.forum.nokia.com/devices/matrix_s60_3ed_fp2_1.html S60 3rd Edition Feature Pack 2], we have to install Open C libraries on the phone. Sending <tt>pips_nokia_1_3_SS.sis</tt> and <tt>stdioserver_s60_1_3_SS.SIS</tt> 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 <tt>config.ini</tt> from [https://bugzilla.mozilla.org/attachment.cgi?id=324627 NSPR for Symbian supporting files], and copy the file to the phone's <tt>C:\system\data\</tt> path with a phone utility called [http://www.drjukka.com/YBrowser.html Y-Browser]. Finally, use Y-Browser to create the folder <tt>C:\data\testlogs</tt> on the phone to store our logs from test cases run.
| |
| | |
| After transferring the ready to install <tt>run_nspr_tests_static.sisx</tt> 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 <tt>nspr_test_log.log</tt> in phone's <tt>C:\data\testlogs</tt>.
| |
| | |
| = Notes =
| |
| | |
| The same as previous section Test, there is an important document [http://docs.google.com/Doc?id=ajdq6jnv2n9s_48hmsfckfx 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 [http://www3.symbian.com/faq.nsf/AllByDate/B8542F039C193CCC802573DA0011DFA7 the GCCE compiler comes with S60 SDK can not produce correct DLL if there are Writable Static Data in it]. Although there is a hope we could use a more recent GCCE release from [http://www.codesourcery.com CodeSourcery], yet there are other problems. So further investigation and workaround have to be carried out.
| |
| | |
| * The reason I put test cases logs in <tt>C:\Data</tt> is that on Windows you could '''''*ONLY*''''' access this phone directory with [http://europe.nokia.com/A4144903 Nonkia PC Suite]. With help of this tool, you will manipulates files on the test device quite conveniently.
| |
| | |
| * If you are using Linux to communicate with the test phone, my suggestion is [http://bluetooth.kmobiletools.org/ KBluetooth] and [http://www.krusader.org/ 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 host. Also an IAP(Internet Access Point) manual selection is needed. So I put this test case as the first one is intended to left you doing your other business without staring at the test device.
| |
| | |
| * According to [http://wiki.forum.nokia.com/index.php/S60_3rd_Edition:_Application_Development#Install_Perl 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.
| |
| | |
| * [http://docs.google.com/Doc?id=ajdq6jnv2n9s_48hmsfckfx More and more...]
| |
| | |
| = Resources Worth Reading/Referencing =
| |
| | |
| * [http://www.forum.nokia.com/main/resources/technologies/symbian/documentation/index.html Forum Nokia Symbian C++ Documentation]
| |
| * [http://wiki.forum.nokia.com/index.php/How_do_I_start_programming_for_Symbian_OS%3F How do I start programming for Symbian OS?]
| |
| * [http://wiki.forum.nokia.com/index.php/S60_3rd_Edition:_Application_Development S60 3rd Edition: Application Development]
| |
| * [http://wiki.forum.nokia.com/index.php/Portal:KB_Symbian_C%2B%2B Forum Nokia Symbian C++ KnowledgeBase]
| |
| * [http://www.symbian.com/developer/techlib/v9.3docs/doc_source/guide/cpp-intro/index.html#DevGuides%2edev%2eabout%2eindex About Symbian OS development]
| |
| * [http://www.symbian.com/developer/techlib/v9.3docs/doc_source/index.html Symbian Developer Library, a.k.a. the ''MSDN'' for Symbian]
| |
| * [http://developer.symbian.com/main/index.jsp Symbian Developer Network portal]
| |
| * [http://developer.symbian.com/wiki/display/pub/P.I.P.S. PIPS Is Posix On Symbian page, just regard this as libc]
| |
| * [http://blogs.forum.nokia.com/blog/harry-lis-forum-nokia-blog My Blog, something about porting Mozilla platform onto Symbian OS]
| |
