Difference between revisions of "SymbianOS"

From Lazarus wiki
Jump to navigationJump to search
m (Categorisation)
 
(41 intermediate revisions by 5 users not shown)
Line 1: Line 1:
The SymbianOS port of Free Pascal is being planned.
+
{{Warning|The work was too large, the platform changed too fast and now the entire SymbianOS is deprecated, so the port was abandoned}}
  
 
==Roadmap to port FPC to SymbianOS==
 
==Roadmap to port FPC to SymbianOS==
  
# Develop a Hello World application on c++ for SymbianOS
+
# <strike>Develop a Hello World application on c++ for SymbianOS UIQ 3</strike> - Felipe
# Convert the Build software from perl to our own building system, and make it build the c++ software.
+
# <strike>Convert the Build software from perl to our own building system, and make it build the c++ software</strike> - Felipe
# Effectively start to port the Free Pascal Runtime Library
+
# <strike>Effectively start to port the Free Pascal Runtime Library</strike> - Felipe
# Convert some c++ symbian applications to check for errors on the port
+
# Convert some c++ symbian applications to check for errors on the port - Felipe - 1 trivial done, more to go
 +
# Complete the port of Free Pascal Runtime Library
 +
# Start developing with UIQ 2 SDK, and make adjustments for everything to work with it
 +
# Make sure everything works on the real Phone with UIQ 2 too
  
===Comments===
+
==Versions Roadmap==
 +
 
 +
The first target will be UIQ 3.0 for the Symbian OS on x86 architecture (the emulator).
 +
 
 +
Next will be the UIQ 2 for x86 emulator, and last the UIQ 2 real device.
 +
 
 +
==Compiling Free Pascal for the Emulator==
 +
 
 +
1 - Download the latest FPC from Subversion. Make sure you also have the latest stable FPC installed.
  
there is also an replacement for the Symbian build system which uses Makefiles: http://www.koeniglich.de/sdk2unix/symbian_sdk_on_unix.html
+
2 - Next you will need a assembler compatible with the Code Warrior linker. Currently this is the GNU Assembler. It´s a good coincidence that the emulator uses normal win32 PE executables, but of course it could use any other format, so FPC will expect a cross-assembler with the correct name. Because of this we can simply copy the as.exe file that comes with FPC releases and rename it.
  
: That build system only targets the ARM device, not the Emulator, and isn´t available for UIQ 3. So it doesn´t help much --[[User:Sekelsenmat|Sekelsenmat]] 16:11, 26 October 2006 (CEST)
+
Suppose your win32 gnu assembler is located at: C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32\as.exe
  
A simpler way would be to concentrate on the POSIX compatible API that Symbian OS has... that would be much faster to do.... And it would not be fixed to UIQ only ...
+
You should make a copy of it with this name: C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32\i386-symbian-as.exe
  
We could  probably reuse existing bindings (for example the Unix rtl or something like that...)
+
3 - Now, open a Windows Command Line session. The following batch script will execute a full compilation of FPC for the emulator. In this particular case lazarus was installed on C:\Programas\lazarus20 and the fpc 2.1 source code is on C:\Programas\fpc21
  
==Versions Roadmap==
+
<pre>
 +
PATH=C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32
 +
cd c:\Programas\fpc21
 +
cd compiler
 +
make i386
 +
cd ..
 +
cd rtl
 +
cd symbian
 +
make FPC=C:\Programas\fpc21\compiler\ppc386.exe
 +
</pre>
 +
 
 +
4 - Building the RTL only is not enougth to compile a Symbian OS application. We also need the c++ bindings which connect our RTL to the Symbian libraries.
 +
 
 +
4.1 - To build the bindings you will need the helper application called mksymbian. This application is included with the Free Pascal sources on the directory utils/mksymbian
 +
 
 +
4.2 - Next compile mksymbian. There is a lazarus project to help building it, but directly calling the compiler from command line works just as well, like this:
 +
 
 +
fpc mksymbian.pas
 +
 
 +
4.3 - Copy the mksymbian executable to the fpc/rtl/symbian/bindings directory, open a console, go to the fpc/rtl/symbian/bindings directory and type this command:
 +
 
 +
mksymbian bindings
 +
 
 +
The resulting .o file(s) will be located on: C:\Programas\fpc21\rtl\units\i386-symbian
 +
 
 +
5 - Next you can go to the session "Building Symbian OS Applications" below, to learn how to use your compiler to generate a Object Pascal software for Symbian.
 +
 
 +
The Symbian OS RTL will be located at: C:\Programas\fpc21\rtl\units\i386-symbian
 +
 
 +
==Compiling Free Pascal for the real device==
 +
 
 +
Not yet implemented.
 +
 
 +
 
 +
==Building Symbian OS Applications==
 +
 
 +
===Overview===
 +
 
 +
Building an application on Symbian OS requires some learning, because there are several unique things about Symbian which must be utilized even the most simple applications. For example the UIDs, the need to register a application on the Emulator, etc.
 +
 
 +
The UIQ SDK has a very complex build system composed of several ten thousends lines of Perl code, batch files and Makefiles. It induces the software to have a specific directory structure, which is very bad to port existing software, as well as to write cross-platform software. Because cross-platform is a strong point on Free Pascal, we decided to simplify and improve the process when writing our build system for Symbian. We created a external build utility, called mksymbian, written in Pascal that auxiliates the build process.
 +
 
 +
===Guide for building applications for the Emulator===
 +
 
 +
You need first to write a .ini file that will contain Symbian OS specific information. Here is a example file called QPasHello.ini
 +
 
 +
<pre>
 +
[Main]
 +
EXENAME=QPasHello.exe
 +
Language=Pascal
 +
ProjectType=EXE
 +
SDK=UIQ
 +
SDKVersion=3
 +
Emulator=1
 +
 
 +
[FPC]
 +
CompilerPath=C:\Programas\fpc21\compiler\ppc386.exe
 +
AssemblerPath=C:\Programas\lazarus215\fpc\2.1.5\bin\i386-win32\as.exe
 +
RTLUnitsDir=C:\Programas\fpc21\rtl\units\i386-symbian\
 +
 
 +
[UIDs]
 +
UID2=0x100039CE
 +
UID3=0xE1000002
 +
 
 +
[Files]
 +
mainsource=QPasHello.pas
 +
mainresource=QPasHello_reg.rss
 +
 
 +
[Objects]
 +
file0=qpashello.o
 +
</pre>
  
The first target will be UIQ 3.0 for the Symbian OS on x86 architecture (the emulator).
+
And the respective QPasHello.pas source file:
  
===Comments===
+
<syntaxhighlight lang="pascal">
 +
{
 +
QPasHello.pas
  
The emulator does not use the E32 fileformat used by the real devices but makes an normal PE exe that bind against the emulator libraries so thath should be much easier to do than to really build ARM binaries... (I don't have Windows right now so I can't test anything yet...)
+
*****************************************************************************
 +
*                                                                          *
 +
*  This demonstration program is public domain, which means no copyright,  *
 +
* but also no warranty!                                                    *
 +
*                                                                          *
 +
*  This program is distributed in the hope that it will be useful,          *
 +
but WITHOUT ANY WARRANTY; without even the implied warranty of          *
 +
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                     *
 +
*                                                                          *
 +
*****************************************************************************
  
: Yes, and that´s why the first target will be the emulator =) --[[User:Sekelsenmat|Sekelsenmat]] 16:11, 26 October 2006 (CEST)
+
This application will create a popup message 'My Hello World' and then quit
  
==The Build Process==
+
The message will last a few seconds.
  
This section is a documentation on the attempt to re-engineer the UIQ 3 build system to a format more friendly to Free Pascal.
+
Author: Felipe Monteiro de Carvalho
 +
}
 +
program QPasHello;
  
===Default SDK Build Process===
+
uses symbian;
  
Two commands are executed when building UIQ 3 software for the emulator. Suppose your UIQ SDK is installed on c:\Symbian\UIQ3SDK and your software C++ source code is on C:\QHelloWorld\src.
+
begin
 +
  User_InfoPrint('My Hello World');
 +
end.
 +
</syntaxhighlight>
  
On C++ you should enter the directory C:\QHelloWorld\group where the build file is located (bld.inf), and type:
+
And also the main resource file QPasHello_reg.rss:
  
 
<pre>
 
<pre>
bldmake bldfiles
+
// QHelloWorld_reg.rss
abld build winscw udeb
+
#include <AppInfo.rh>
 +
UID2 0x100039CE
 +
UID3 0xE1000002
 +
RESOURCE APP_REGISTRATION_INFO
 +
{
 +
  // filename of app binary (minus extension)
 +
  app_file = "QPasHello";
 +
}
 
</pre>
 
</pre>
  
The first command will:
+
Next use mksymbian to build your application, like this:
 +
 
 +
mksymbian build QPasHello.ini
  
* Generate the directory: C:\Symbian\UIQ3SDK\epoc32\BUILD\Programas\SymbianOS\QHelloWorld\group
+
If something goes wrong, check if mksymbian located your directories correctly:
  
*Fill it with many Makefiles
+
mksymbian showpath
  
*Create a ABLD.BAT script
+
Also make sure to correct the paths according to your system on the ini file.
  
*Perl files involved: bldmake.pl
+
===Using mksymbian===
  
The second command will:
+
The syntax of this tool is:
  
*Generate the directory: C:\Symbian\UIQ3SDK\epoc32\BUILD\Programas\SymbianOS\QHelloWorld\group\QHELLOWORLD\WINSCW
+
mksymbian [action] [project file]
  
*There it will put the source code, a QHELLOWORLD.WINSCW file and a UDEB directory with compiled .o files for the software
+
Action can be one of the following:
 +
* build - Compiles a project
 +
* bindings - Compiles the pascal bindings for Symbian OS. It supposes that the necessary files are on the location where the command is executed.
 +
* showpath - Shows the paths found for the Symbian SDKs and Free Pascal. Utilized to check if the tool was able to find the tools.
  
*It will also create a executable (QHelloWorld.exe) for the software on the directory: C:\Symbian\UIQ3SDK\epoc32\release\winscw\udeb
+
The project file is a .ini file with many symbian os specific informations about a project, like the UIDs
  
*Perl files involved: abld.pl makmake.pl
+
Target can be one of the following:
  
===Modifyed Build Process===
+
* WinEmulator - Builds for the x86 emulator
 +
* ArmDevice - Builds a binary for use on PDAs and Smartphones
  
To aid on this complex build process, a command line tool called "mksymbian" will be created.
+
Note: The tool parameters are not case-sensitive
  
Default UIQ build process expects that the source be on a rather peculiar directory format. This is unsuitable for cross-platform development. Just imagine if each OS required a different directory tree, cross-platform would be impossible. Instead we will change this to simply require that the project be the only project on it´s directory. This is already required by many tools, like make, so it should be a flexible enougth restriction for cross-platform.
+
==Screenshots==
  
On the folder of the project you should have source code and also a project information file. This file is in INI format, and specifies many information for our tool to use to build the project. The file must be called "mksymbian.ini"
+
First pascal symbian os UIQ 3 application:
  
To compile a C++ project with it you can do:
+
[[Image:First_pascal_symbian_app.PNG]]
  
mksymbian cpp
+
==See Also==
  
This is just utilized to show that the tool produces correct output, as our objetive here is to build Object Pascal software.
+
*[[Programming in Symbian OS]]
 +
*[[Symbian OS Internals]]
  
 
==External Links==
 
==External Links==
  
 
* http://developer.uiq.com/ - UIQ version 3 and superior developer community, with SDK download, Forum, Documentation and News.
 
* http://developer.uiq.com/ - UIQ version 3 and superior developer community, with SDK download, Forum, Documentation and News.
* http://www.symbian.com/developer/techlib/v70sdocs/doc_source/reference/cpp/libc/index.html  docs for the POSIX layer  
+
* [http://www.symbian.com/developer/techlib/v70sdocs/doc_source/reference/cpp/libc/index.html] docs for the POSIX layer  
* http://www.symbian.com/developer/techlib/v70sdocs/doc_source/devguides/cpp/base/CStandardLibrary/DesignSTDLIB.html  a bit of description for the POSIX layer
+
* [http://www.symbian.com/developer/techlib/v70sdocs/doc_source/devguides/cpp/base/CStandardLibrary/DesignSTDLIB.html] a bit of description for the POSIX layer
* compiling perl for symbian http://search.cpan.org/~rgarcia/perl-5.9.4/README.symbian they mainly use the POSIX libraries...
+
* [http://search.cpan.org/~rgarcia/perl-5.9.4/README.symbian] - Compiling perl for symbian. They mainly use the POSIX libraries...
 +
* [https://developer.uiq.com/forum/entry.jspa?externalID=31] - List of the UIQ Phones and the UIQ SDK version to use.
 +
* [https://developer.uiq.com/forum/kbclick.jspa?categoryID=21&externalID=26&searchID=101700] - APIs changed from UIQ 2.1 to UIQ 3
 +
* [https://developer.uiq.com/forum/kbclick.jspa?categoryID=21&externalID=20&searchID=101700] - How to port my application from UIQ 2.x to UIQ 3
 +
 
 +
[[Category:Symbian]]
 +
[[Category:Mobile]]
 +
[[Category:Historical]]
 +
[[Category:Outdated information]]

Latest revision as of 21:56, 6 June 2021

Warning-icon.png

Warning: The work was too large, the platform changed too fast and now the entire SymbianOS is deprecated, so the port was abandoned

Roadmap to port FPC to SymbianOS

  1. Develop a Hello World application on c++ for SymbianOS UIQ 3 - Felipe
  2. Convert the Build software from perl to our own building system, and make it build the c++ software - Felipe
  3. Effectively start to port the Free Pascal Runtime Library - Felipe
  4. Convert some c++ symbian applications to check for errors on the port - Felipe - 1 trivial done, more to go
  5. Complete the port of Free Pascal Runtime Library
  6. Start developing with UIQ 2 SDK, and make adjustments for everything to work with it
  7. Make sure everything works on the real Phone with UIQ 2 too

Versions Roadmap

The first target will be UIQ 3.0 for the Symbian OS on x86 architecture (the emulator).

Next will be the UIQ 2 for x86 emulator, and last the UIQ 2 real device.

Compiling Free Pascal for the Emulator

1 - Download the latest FPC from Subversion. Make sure you also have the latest stable FPC installed.

2 - Next you will need a assembler compatible with the Code Warrior linker. Currently this is the GNU Assembler. It´s a good coincidence that the emulator uses normal win32 PE executables, but of course it could use any other format, so FPC will expect a cross-assembler with the correct name. Because of this we can simply copy the as.exe file that comes with FPC releases and rename it.

Suppose your win32 gnu assembler is located at: C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32\as.exe

You should make a copy of it with this name: C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32\i386-symbian-as.exe

3 - Now, open a Windows Command Line session. The following batch script will execute a full compilation of FPC for the emulator. In this particular case lazarus was installed on C:\Programas\lazarus20 and the fpc 2.1 source code is on C:\Programas\fpc21

PATH=C:\Programas\lazarus20\fpc\2.0.4\bin\i386-win32
cd c:\Programas\fpc21
cd compiler
make i386
cd ..
cd rtl
cd symbian
make FPC=C:\Programas\fpc21\compiler\ppc386.exe

4 - Building the RTL only is not enougth to compile a Symbian OS application. We also need the c++ bindings which connect our RTL to the Symbian libraries.

4.1 - To build the bindings you will need the helper application called mksymbian. This application is included with the Free Pascal sources on the directory utils/mksymbian

4.2 - Next compile mksymbian. There is a lazarus project to help building it, but directly calling the compiler from command line works just as well, like this:

fpc mksymbian.pas

4.3 - Copy the mksymbian executable to the fpc/rtl/symbian/bindings directory, open a console, go to the fpc/rtl/symbian/bindings directory and type this command:

mksymbian bindings

The resulting .o file(s) will be located on: C:\Programas\fpc21\rtl\units\i386-symbian

5 - Next you can go to the session "Building Symbian OS Applications" below, to learn how to use your compiler to generate a Object Pascal software for Symbian.

The Symbian OS RTL will be located at: C:\Programas\fpc21\rtl\units\i386-symbian

Compiling Free Pascal for the real device

Not yet implemented.


Building Symbian OS Applications

Overview

Building an application on Symbian OS requires some learning, because there are several unique things about Symbian which must be utilized even the most simple applications. For example the UIDs, the need to register a application on the Emulator, etc.

The UIQ SDK has a very complex build system composed of several ten thousends lines of Perl code, batch files and Makefiles. It induces the software to have a specific directory structure, which is very bad to port existing software, as well as to write cross-platform software. Because cross-platform is a strong point on Free Pascal, we decided to simplify and improve the process when writing our build system for Symbian. We created a external build utility, called mksymbian, written in Pascal that auxiliates the build process.

Guide for building applications for the Emulator

You need first to write a .ini file that will contain Symbian OS specific information. Here is a example file called QPasHello.ini

[Main]
EXENAME=QPasHello.exe
Language=Pascal
ProjectType=EXE
SDK=UIQ
SDKVersion=3
Emulator=1

[FPC]
CompilerPath=C:\Programas\fpc21\compiler\ppc386.exe
AssemblerPath=C:\Programas\lazarus215\fpc\2.1.5\bin\i386-win32\as.exe
RTLUnitsDir=C:\Programas\fpc21\rtl\units\i386-symbian\

[UIDs]
UID2=0x100039CE
UID3=0xE1000002

[Files]
mainsource=QPasHello.pas
mainresource=QPasHello_reg.rss

[Objects]
file0=qpashello.o

And the respective QPasHello.pas source file:

{
 QPasHello.pas

 *****************************************************************************
 *                                                                           *
 *  This demonstration program is public domain, which means no copyright,   *
 * but also no warranty!                                                     *
 *                                                                           *
 *  This program is distributed in the hope that it will be useful,          *
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of           *
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                     *
 *                                                                           *
 *****************************************************************************

 This application will create a popup message 'My Hello World' and then quit

 The message will last a few seconds.

 Author: Felipe Monteiro de Carvalho
}
program QPasHello;

uses symbian;

begin
  User_InfoPrint('My Hello World');
end.

And also the main resource file QPasHello_reg.rss:

// QHelloWorld_reg.rss
#include <AppInfo.rh>
UID2 0x100039CE
UID3 0xE1000002
RESOURCE APP_REGISTRATION_INFO
{
  // filename of app binary (minus extension)
  app_file = "QPasHello";
}

Next use mksymbian to build your application, like this:

mksymbian build QPasHello.ini

If something goes wrong, check if mksymbian located your directories correctly:

mksymbian showpath

Also make sure to correct the paths according to your system on the ini file.

Using mksymbian

The syntax of this tool is:

mksymbian [action] [project file]

Action can be one of the following:

  • build - Compiles a project
  • bindings - Compiles the pascal bindings for Symbian OS. It supposes that the necessary files are on the location where the command is executed.
  • showpath - Shows the paths found for the Symbian SDKs and Free Pascal. Utilized to check if the tool was able to find the tools.

The project file is a .ini file with many symbian os specific informations about a project, like the UIDs

Target can be one of the following:

  • WinEmulator - Builds for the x86 emulator
  • ArmDevice - Builds a binary for use on PDAs and Smartphones

Note: The tool parameters are not case-sensitive

Screenshots

First pascal symbian os UIQ 3 application:

First pascal symbian app.PNG

See Also

External Links

  • http://developer.uiq.com/ - UIQ version 3 and superior developer community, with SDK download, Forum, Documentation and News.
  • [1] docs for the POSIX layer
  • [2] a bit of description for the POSIX layer
  • [3] - Compiling perl for symbian. They mainly use the POSIX libraries...
  • [4] - List of the UIQ Phones and the UIQ SDK version to use.
  • [5] - APIs changed from UIQ 2.1 to UIQ 3
  • [6] - How to port my application from UIQ 2.x to UIQ 3