GnuPoc SDK patches
==================

Installation
------------

Start by installing the toolchain for your SDK, see tools/README in this
package, or see instructions at http://www.martin.st/symbian/.

These patches use the native version of tools, if they are availble
in the toolchain directory, otherwise it reverts to use the original
versions through wine.

Then download the SDK you want to install, from Forum Nokia
(www.forum.nokia.com) or UIQ Developer Community (developer.uiq.com).
The following versions are supported at the moment:

S60 1st Edition, FP1, WINS		nS60_sdk_v1_2.zip
S60 2nd Edition, WINS			s60_sdk_v2_0.zip
S60 2nd Edition, FP1, WINS		S60_SDK_2_1_NET.zip
S60 2nd Edition, FP1, CW		S60_SDK_v21c_CW.zip
S60 2nd Edition, FP2, WINS		s60_2nd_fp2_sdk_msb.zip
S60 2nd Edition, FP2, CW		s60_2nd_fp2_sdk.zip
S60 2nd Edition, FP3			s60_2nd_sdk_fp3.zip
S60 3rd Edition, Maintenance Release	S60-SDK-0616-3.0-mr.3.749.zip
S60 3rd Edition, FP 1			S60_SDK_3.1_CPP_v1.0.1_en.zip
S60 3rd Edition, FP 2			S60_SDK_3.2_v1.1.1_en.zip
S60 5th Edition				S60_5th_SDK_ASP_v1.0.1.zip
N97 SDK					Nokia_N97_SDK_v1_0_en.zip
Symbian^3				Symbian_3_SDK_v1_0_en.zip
UIQ 3.0					UIQ3.0SDK.exe
UIQ 3.1					UIQ3.1SDK.exe

Unpacking of all S60 SDKs except 2.1 for WINS requires unshield, the UIQ
SDKs require p7zip. Both unshield and p7zip are included in this package,
as precompiled binaries for linux/x86 and as source code. The S60 2.1 WINS
SDK requires cabextract, which isn't included. If not running on linux/x86,
see the files unshield/README or 7z/README for instructions on compiling
these.

Install them using the matching install scripts, e.g.:
./install_gnupoc_s60_30 ../S60-SDK-0616-3.0-mr.3.749.zip ~/symbian-sdks/s60_30

If you're going to use some tools through wine (e.g. rcomp, petran),
you have to copy uidcrc.exe from the epoc32/tools directory within your
newly installed SDK to a directory within your wine path, e.g.
~/.wine/drive_c/windows. It shouldn't matter which SDK you copy this from.

If using external makefiles (e.g. for building icons in 3rd edition)
using wine, copy make.exe and mifconv.exe, too. make.exe probably can
be used from any SDK version, but you'll need mifconv.exe from the 3.0
SDK, since mifconv.exe in 3.1 has some problems starting within wine.

Then finally install wrapper scripts:
./install_wrapper ~/gnupoc

If you installed the toolchain into nonstandard directories, edit
~/gnupoc/gnupoc-common.sh and set EKA1TOOLS and EKA2TOOLS to point to the
directories where you installed the tools.

When using the SDK, add the ~/gnupoc directory to your PATH:
export PATH=~/gnupoc:$PATH

And set the EPOCROOT variable to point to your SDK:
export EPOCROOT=~/symbian-sdks/s60_30/


As an alternative to using the wrapper script directory, you can opt to
manually add the toolchain and epoc32/tools directory to your path.

export PATH=~/csl-gcc/bin:${EPOCROOT}epoc32/tools:${PATH}

See details in gnupoc-common.sh for more detailed info on what other env
variables may need to be set up.


These installations can also use the Visual C++ 2003 and/or Codewarrior
compilers. Make sure the binaries are within the wine path. For Codewarrior,
you also have to set the MWCSym2Includes, MWSym2Libraries and
MWSym2LibraryFiles variables in the unix environment, since the perl build
scripts need them for determining the compiler version.



The tools for compiling context-sensitive help require wine. Additionally,
they need the wrapper scripts to be installed as described above.

One of the tools run through wine spawns a wine console. This by default
tries to launch an x11 based console window. In wine version 1.1.3,
the console correctly falls back to curses if unable to create a separate
console window. In practice, this means that this tool requires a working
x server, when using wine versions less than 1.1.3. To force it to use a
curses based console on earlier wine versions (if no x server is
available), edit epoc32/tools/cshlpcmp/perl/cshlpfl.pm and change "wine"
(on line 144) into "wineconsole --backend=curses".



Usage
-----

After installing everything, you're able to compile things in the same way
as on windows. The install scripts clean up the usage of lower/upper case
in the bundled examples (by forcing them to lowercase), so they should all
be buildable directly. (Or at least it tries to, it might not work reliably
in stranger examples.) To build the hello world example, do the following:

export PATH=~/gnupoc:${PATH}
export EPOCROOT=~/symbian-sdks/s60_30/
cd ${EPOCROOT}/s60ex/helloworldbasic/group
bldmake bldfiles
abld build gcce urel
cd ../sis
makesis helloworldbasic_gcce.pkg helloworldbasic.sis

Then create a self-signed certificate if you haven't got one already:
makekeys -cert -expdays 3650 -password mykey.key mycert.cer

Then sign the sis file using this certificate and key:
sign.sh helloworldbasic.sis helloworldbasic.sisx mycert.cer mykey.key

The certificate and signing is only needed on Series 60 3rd edition.


Sharing an installation
-----------------------

If the SDK installation is to be shared by many users on a multiuser
system, one might want to install a read-only copy of the SDK.

However, the Symbian SDK structure requires every user to be able to
write to the SDK, especially to the epoc32/build directory. A solution
to this is to create a writeable copy of the directory structure, where
all the original files are symbolic links to the original copies. (It
still uses quite a bit of diskspace, but remarkably less than the whole
SDK.)

The included script makelinkdir can be used to create such a copy of the
directory structure. If a read-only copy of the SDK is installed in
e.g. /usr/local/symbian-sdks/s60_21_cw/, a user can create a usable
copy of his own of the SDK:

./makelinkdir /usr/local/symbian-sdks/s60_21_cw ~/symbian-sdks/s60_21_cw
export EPOCROOT=~/symbian-sdks/s60_21_cw

At this stage, all the files which were installed in the SDK are available
in this local copy as links to read-only files. This works fine for
building code, which only creates new files and directories. But for running
the emulator, the existing files within the epoc32/wins(cw) directory must
be writeable. In that case, do the following:

cd ~/symbian-sdks/s60_21_cw/epoc32
rm -rf winscw
cp -Lr /usr/local/symbian-sdks/s60_21_cw/epoc32/winscw .
chmod -R u+w winscw

That is, the epoc32/winscw directory is replaced with a copy containing
real writeable copies of all files.


License
-------

The patches are based on earlier GnuPoc patches by Alfred E. Heggestad
and modified by me. The patches and the accompanying installation scripts
are redistributable and usable according to the Gnu Public License (GPL),
see the COPYING file. This only covers the patches, though; the use and
redistribution of the SDKs still is restricted by their end user license
agreements.



Martin Storsjo
[email protected]