main index FIRST OF ALL, did you read all of my P900 notes?

Here I show my P900 C++ UIQ SDK for Linux solution. This work must be considered "under GNU GPL license".

I start from the original UIQ 2.1 SDK, fetch the minimum needed files, and then show how to use the simplest Makefile to get a program compiled, linked, and enveloped in a .SIS file. I must thank Alfred for his great gnupoc work and for his precious help to get done everything presented in this page.

Note: if you were searching for P900 C++ development with Apple Mac OS X, then have a look at Simon's site!


Quick index:

Latest news:

Please note:


Frequently asked questions


How to create the "P900 C++ UIQ SDK for Linux"

Before you start, you need to download some tools:

  1. First, get the official Symbian/UIQ 2.1 SDK (I took the Metrowerks one, more than 220Mb of download: ouch! The Borland one, which is 160Mb, shows some errors while extracting by some unzip utilities under Linux; probably it's only an old unzip fault - you've been warned!). This package contains official include files, libraries, and full HTML documentation.

  2. You also need the gcc-arm-thumb-epoc-pe-539 compiler (almost 14Mb of download: get the binary release, unless you are very familiar with patching and compiling huge programs (the latest version I saw was "build 546"; the patches are downloadable on Symbian site). In this page I refer to the binary release "539". This package contains the Linux executables of a gcc compiler for ARM/Thumb platform suitable for an Epoc/Symbian system.

  3. You need the Sony Ericsson P900 (SEMC UIQ SDK) extensions (note: it's also named "P800/P900/P910 specific C++ API for UIQ 2.1 SDK"; you should also find it in the same page of Symbian/UIQ 2.1 SDK); download is enabled after a (free) registration procedure. This package contains extra include files, libraries and documentation for using the P900 features not directly supported by the Symbian/UIQ: the vibration engine, the digital camera (for photos and videos) and the AMR (Adaptive Multi-Rate speech coding) audio streaming (encoding/decoding).

  4. I do not support Beatnik Audio Engine API extensions; maybe you'll want to experiment with them and drop me a note in case you place in your home pages some functional examples...

  5. Make sure you have Wine installed on your system (it's common on almost any distribution, SuSE, RedHat, Debian, etc. Anyways, Wine will be used in text-only mode, only for command-line utilities).

No, you don't need gnupoc to continue. Yes, I verified the above links on late December 2005 (they are up at least from Oct'2003).

First step: extract/install the SEMC extensions under Wine. YES, I do know that this is boring, but I was in a hurry and I couldn't figure out in a few seconds a cleaner mode to extract that .EXE file using only Linux tools. After starting it (using the "wine -- SEMC_UIQ_SDK_EXT.exe" command) you will get a "C:\SYMBIAN" directory tree under your Wine "disk". In my SuSE Linux distribution I found it in the .wine/fake_windows/Symbian subdirectory of my home directory.

Second step: uncompress (do not install: unzip it only!) the UIQ 2.1 SDK package in the /tmp directory. You should get there a directory named "UIQ 2.1 SDK WINSCW Candidate 2" containing about 230Mb of package files named something like com.symbian.api...sdkpkg (these are actually zip archives) and a number of extra useless files (setup.exe, etc).

NOTE: this page describes the steps about "Candidate 2" release. The final release has some minor differences (one of the example directories is not there, so some mv commands will apparently fail during installation. Anyways, commenting out them will let you go on. I will post some extra information in some days (hold on!).

Third step: uncompress the gcc package described above, using this command (you need to be root because you will extract on the root directory):
tar xpjvf gcc-arm-thumb-epoc-pe.539-2aeh.linux.i386.tar.bz2 -C /

This will create the directory tree /usr/local/er6 containing the gcc for ARM/Epoc/etc. Since I do not like lots of directory trees around, we will install the useful UIQ SDK components under /usr/local/er6/sdk (I didn't even try to move it to another directory because it seems that the gcc executables refer to /usr/local/er6 - anyways, an experienced user may be able to build everything to some other directory; to make things easier I won't fiddle with $PATH).

Before going on, make sure you still have at least 400Mb of free disk space.

Now download the p900uiqsdkforlinux package here; uncompress it somewhere (you need to use the "tar xpjvf" command): it contains a few example sources and the p900uiqsdkforlinux.sh script. Edit this script and modify it for your needs (the first dozen of lines contains everything, but if you follow my scheme you don't need to change anything). Then, execute the script.

The script will show some little information and will do minimal checks to get sure that everything is in its place; then it will lower its priority and start uncompressing packages around. Then it will erase unneeded stuff, and convert the 1800+ include files. It will require some minutes to complete everything. If for any reason it fails, then erase the files in /usr/local/er6/sdk/ and start again.

Notice that it expects an empty and writeable /usr/local/er6/sdk directory, and will copy the extracted uidcrc.exe file in the C:\WINDOWS directory of the Wine (this also is specified in the first dozen of lines).

To work without root privileges one can create the /usr/local/er6/sdk directory and change owner; for example I (user alfmar) did this on my SuSE Linux (and soon after left root mode):
mkdir /usr/local/er6/sdk
chown alfmar.users /usr/local/er6/sdk

Warning: this script also expects that the perl, tr, unzip, touch... programs and utilities to be reachable in the current path (this should be true for every recent Linux distribution). It also creates and uses some temporary Perl scripts, and even creates and compiles two C programs (one of them, genaif, is taken from sdk2unix package; thanks, Rudolf!).

Once the script has completed the installation, you will have the /usr/local/er6 directory tree containing everything. When you will want to "uninstall" it, do simply remove that directory and its contents, and the uidcrc.exe from the C:\WINDOWS emulated directory of Wine.

Now you can have a look at the examples. Enter the linuxhello1 directory and look at its Makefile to see how you will use it. YES, it's actually the simplest you could imagine:
#
# makefile for "Hello from Linux world" application
#

# --- configuration

APP = HelloLinux
DSC = Hello Linux World!

CPP = application appui appview document main
RSC = helloworld
LIB = euser apparc cone eikcore eikcoctl

UID = 0b2c9cb6
VER = 1.00

include /usr/local/er6/sdk/rules

You just have to define some things about the project, and then start make which will do all steps in the correct sequence, with minimal diagnostic output (sigh! the petran.exe does not have a "quiet" switch). The mandatory options are:

  1. APP - the application directory/program name (here I set "HelloLinux": this means that once installed on the memorystickduo of the P900, a D:\System\Apps\HelloLinux directory will be created, containing at least HelloLinux.app and HelloLinux.rsc files); I suggest to use only alphanumeric characters (including "_");

  2. DSC - the short program description (this string will be seen when installing the final .SIS file, in the Uninstall Launcher section, etc);

  3. CPP - the list of C++ sources, without .cpp extension;

  4. RSC - the resource file name, without .rss extension (as for C++ sources, it is not required to use the application name; the rules file will add everything needed);

  5. LIB - the libraries to link against (without .lib extension);

  6. UID - the application unique identifier (UID, sometimes referred as UID3 in the UIQ SDK documentation or articles), of eight hexadecimal digits, without leading "0x"; in this example I used a "development value"; please read here some notes about using UIDs;

  7. VER - the program version number, always in the strict form "digit dot digit digit" (I suggest to use from 0.01 to 9.99); in the above example I used "1.00";

  8. finally, include the "rules" file to make everything from the SDK directory.

Note: this is a Makefile - you can add extra commands, which will be parsed before the rules) or use equivalent definitions; for example the CPP line can be split in these two lines:
CPP = application appui appview
CPP += document main

The rules file contains rules and definitions for the generation of all intermediate and final files for a P900 .SIS package installation for the application. It will do some (small) sanity checks, then compilation, linkage, and envelop in a .SIS file named (in this case) LinuxHello_1.00.sis (the version number in the .sis file name is not actually needed, but will save you some headaches when browsing a directory listing or beaming something to the P900).

While the rules are decently written (I hope!) and will try to do only the needed steps, in a number of cases you will need to issue a make clean command before rebuilding (for example, when adding a library file or changing the UID). Warning: the make clean will also erase every .sis file!

Also, in the linuxhello1 directory you can see there are five C++ (.cpp) source files, two include files (a .h and a .hrh file), and a .rss resource file. Yes, it just was the common HelloWorld example of the original UIQ 2.1 SDK... I only made their filenames more "human", and changed some other little things. One of these changes is that you need to define the application unique identifier (UID, sometimes referred as UID3) in only one place - that is, in the Makefile. The rules will take it and pass to the C++ sources, so that you don't have lots of UID definitions hanging around...! See the application.cpp source file to know how to use the "__UID__" macro.
There is also a macro "__VER__", which is defined as a string containing the version number (so you don't need to have lots of version numbers around!) and a macro "__APP__", which is defined as a string containing the application name (the APP value of above).

As you can see, issuing a make command will build everything and fill the local directory with temporary files (there were 9 source files, including the Makefile, and at the end you will see 26 files in your directory!). In my humble opinion this little "chaos" is useful to see in every moment if there has been some problem (and examine the size or aspect of an intermediate file to see what went wrong). The only important file to save out of a make build is the .sis file, to be beamed to the P900 using obex_p900 (or some similar tool) via infrared, email, Bluetooth, etc (note: at leas KDE 3.2 has, in the right-click menus of files, a "Bluetooth send" option in the "Actions" sub-menu: I tested it and it works!). A make clean will wipe out all intermediate and final files.

The make process does not show details of what is happening; if you want, you can edit the rules file and get rid of those '@' before the compile and link commands in the "general compilation rules" part of the file, to see what commands make executes. On my Pentium III 750MHz notebook it takes less than 45 seconds to build the .sis file from scratch, mostly of C++ compiling time.

After compiling and installing it on the P900 you will see the "HelloLinux" in the Launcher, with the common "blue diamond" icon. While you will see that while it requires only six kilobytes, sometimes its installation may decrease the memorystickduo available space of 0,1Mb (this is because the memorystickduo is formatted with big clusters, which waste space for little files, but are a bit quicker for using large files like large MP3 songs). I already said that you should avoid as much as possible the installing of programs on the core memory ("C:" disk): do use always the memorystickduo ("D:" disk) of the P900!

Maybe you are wondering what the heck are all those "intermediate" files. This is only what Symbian people intend for "building applications". You would expect to compile some sources, link against some libraries, and get an executable ready to go. The Symbian/UIQ applications (sometimes named "GUI", i.e.: "graphical user interface") are not the common executable files (also known as .EXE files) but dinamically linked libraries (also known as .DLL files) that use a .APP file extension (this is because Symbian also has its own .EXE and .DLL formats but they are not intended for GUI applications).

The minimal GUI application consists of two files (the .APP and the .RSC binary resource file). The UIQ loads the .APP (remember: it actually is in .DLL format) and keeps it in the core memory also when it "looses focus" (that is, when the application is not in use). When in urgent need of memory, the UIQ closes the applications (you should read "unloads those .DLL programs") that are not in use. This is to speed up daily usage (switching to another GUI application is almost always immediate).

The steps to build an application - i.e. the work done by the Makefile above - are described here (not in chronological order):

  1. build the .o object files starting from .cpp sources;
  2. build the .inf text file from the object files using dlltool to get information about the "entry point" of this new application;
  3. build the .bas binary "base file" from the .inf file, using the linker;
  4. build the .exp binary information data file from the .bas file, using again the dlltool utility;
  5. build the .cmd executable file from the .exp file, linking all object files and libraries; notice that this seems a relocatable Microsoft/i386 protected-mode executable 32-bit DLL (actually it has a Microsoft header, but contains ARM code), because this is what the gcc539 linker gave out (ouch!);
  6. build the .app file starting from the .cmd file (add specific UIDs and replace the Microsoft header with the Symbian header, using the petran utility);
  7. build the .rsc binary resource file from the .rss source;
  8. build a .pkg description text file suitable for makesis program, containing the appropriate UIDs and at least the .app and the .rsc file;
  9. build the .sis compressed package file using files and details of the .pkg file.

Let's go now in the linuxhello2 directory, and let's have a look to the Makefile. This is similar to linuxhello1 one, except for some good news:
#
# makefile for P900 Hello Linux World application
#

# --- configuration

APP = LinuxHello
DSC = Hello Linux World!

CPP = application appui appview document main
RSC = helloworld
LIC = license
LIB = euser apparc cone eikcore eikcoctl gdi vibration
BMP = icon icon_mask icon_small icon_small_mask

UID = 0b2c9cb7
VER = 2.00

include /usr/local/er6/sdk/rules

As you can see, you can also add a "license" text which will be shown during the installation on the P900. The license file (to be specified in the optional LIC field, without appending the .txt extension) is a short CR/LF-terminated text file which will get automatically wrapped (a scroll bar will be added if the file is longer than a screen). The P900 installer will ask for "Yes" or "No" (if the user taps on "No", the installation will be aborted). I argue you won't be stupid and won't use it for more than one or two screens of text, neither you will use it to annoy the user by only writing "Tap on Yes to continue installation"...!

Also, one can specify the icon pairs (in the optional BMP field line of the Makefile) to be enclosed in the UIQ application information file (the mighty .aif file). These have to be in .bmp (Windows bitmap) format, because this is the format accepted by the bmconv.exe utility (which creates a .mbm multiple bitmap, suitable for the .aif application interface file). As you can see, I specified two pairs: the "big" icon (size 32×32), with its "bit-mask" (of the same resolution; the bit-mask is the area in which it's not transparent to the background), and the "small" icon (size 20×16; as of UIQ documentation, it can be up to 24×20 in size, but the suggested size is 20×16) and its related bit-mask. The bitmap files do not need to be named "icon..." (I did it only to be self-explanatory).

Once installed, these bitmaps will be shown in the Launcher instead of the default "blue diamond" icon (yes, also when you use the "Icon view" instead of "List view": go onto it by rolling the jogdial, and you will see the "big" icon). Extra bonus added: in the .aif application there was also specified the program description (the DSC field explained above!), so we will see "Hello Linux World!" on the Launcher list instead of "HelloLinux" or "LinuxHello".

You surely noticed that the application name (APP) is no longer "HelloLinux", and the UID is different. If you use the same UID, then the P900 will ask you to uninstall the "previous" package (arguing that this package and the one compiled before are the same program, even if they use different filenames and directory names!). If you use a different UID but the same "HelloLinux" application/directory name, then the P900 will overwrite the original "HelloLinux" directory (ouch!). This is why I called it "LinuxHello" instead of "HelloLinux": I made the application name (and the UID) different, to get the two programs installed on the P900 in the same moment without overwriting anything. Notice also that the version number is only for on-screen information (in fact one can install an "old" version of any program, erasing its supposedly "recent" version).

If you get rid of the first icon pair, then you will get only the "small" icon (and icon mask): in the Launcher "Icon view" you will see the "small" icon only, even if selected.

You can draw and edit icons using the Gimp, which is normally available in every Linux distribution. I suggest to use 256-color format (8 bit per pixel). One can easily load any JPEG/PNG image file and cut it and reduce it to 20×16 pixels and 8-bit palette colors, and save as .bmp file (the mask can be cut down to 1-bit-per-pixel, using white for transparent areas and black for colored areas). Remember to not to use the RLE-encoding, because the bmconv.exe utility program does not recognize it.

But this application contains something more... Edit the appview.cpp file and go to the CExampleAppView::Draw function. I used a number of graphics commands and even the P900's vibration engine! This is why you see the two extra libraries linked (gdi and vibration). I found the description of those graphics commands in the UIQ documentation (starting from /usr/local/er6/sdk/doc/index.html) and in the Sony Ericsson P900 Extensions documentation (starting from /usr/local/er6/sdk/semc/index.html). Remember that the vibration command is ignored by the operating system when the P900 battery is charging. Also, you will notice that this program will activate the vibration often... this happens because the vibration command is in the Draw function, which gets called every time its window has to be (partially or totally) redrawn, for example when an "infoprint" message expired (the program uses "infoprints" to say "Linux!" on screen when you select some menu options: have a look!).

Well, organizing a build of C++ sources (and resources, and bitmaps, and license text file) is now quite easy; you don't get the bunch of options and features of the Windows-based UIQ SDK, but you will be able to build a new P900 application without fighting too much...!

How to start from scratch a new application:


Uh-oh. I just added support for EXE file type. I only added a number of rules in the "rules" Makefile; it's a quick hack but it saves the two common situations: an APP that just launches the EXE and then dies, and a complex APP that may launch an EXE when needed. Again, everything can be quietly enclosed in a SIS file.

I added the "consoledemo" example: it's a "console" type executable (an EXE program) which gets launched from a common APP program. This means that one can work on the EXE program without worrying about Symbian/UIQ details (the SIS file that must start an APP program which will launch the EXE file, etc). I got inspiration and information by two of the most famous "full screen" applications: Yipton's EDoom and Rudolf's p3nfs nfsapp.

If you want to add an EXE program to a package, follow the normal APP instructions above, and add these two lines in your Makefile:

Yes, the APP program will have its .cpp source files, while the EXE file will have its .c++ sources (this should help to avoid confusion: "is this source APP's one or EXE's one?"... but you will need also to use different names for sources; don't use "test.cpp" if there is already a "test.c++" in the same directory!).

The "consoledemo" example also features reading of jog-dial events (it just loops waiting for a system event).


This "P900 UIQ SDK for Linux" work is not perfect:

  1. it still doesn't handle dependencies;
  2. it supports only APP and EXE types, i.e. GUI applications (or a GUI application that launches an EXE program, for example a "console" based program); currently it doesn't support Symbian weird targets (like DLL libraries or such things);
  3. it still doesn't have any support for multi-language (resource, application name, license textfiles, packaging);
  4. it still doesn't support building of intermediate files in a temporary directory;
  5. it should use other make features ("phony", "precious", etc);
  6. it could clean out more stuff at installation time (useless gcc539 executables, some of the 480+ SDK libraries, some of the 1800+ SDK include files, etc);
  7. it should use Linux versions of rcomp, makesis, uidcrc, etc - this means that Wine should not be needed anymore, thus letting you to port everything to ANY non-Intel Linux platform!!!

I also got a few bug-reports (will be fixed in next release):


Some final considerations and notes...

Yes, there is someone who asked "I want to write my own programs... is there out any non-Linux solution?" (it just happened! there is some people out there for which you need Linux to write C++ software for the P900! YAY!)

I spent lots of hours to get to this solution, without any feedback by Symbian or Sony Ericsson people (there was actually some little feedback, but it was mainly related to my site and my severe considerations about P900 bugs and missing features).

Sony Ericsson people and Symbian people should ask theirselves why all this Linux support for their products comes free to them, without extra costs, and raising (at least) more hype than a new advertisement campaign. They should also ask theirselves why some people like me spend the biggest part of available spare time to "join" Linux to such a machine. This is not a matter of opinions about Linux: this is a fact.


Google
 
Web www.alfonsomartone.itb.it

November 6, 2003: yes, I got it!

Sony Ericsson P900 index - send e-mail - home page