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-200634-3.1-Cpp-f.1090b.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 and source. The S60 2.1 WINS SDK requires cabextract,
which isn't included.

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.

When using the SDKs, set the EPOCROOT variable to point to your SDK and
add the epoc32/tools directory and your toolchain to your PATH, e.g.:

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

Or, more conveniently, install wrapper scripts:
./install_wrapper ~/gnupoc

Using these wrapper scripts, you only have to add the wrapper directory to
your PATH, and the wrappers call the correct tools depending on the EPOCROOT
variable. The wrappers also include sign.sh, to avoid having to enter
the key password on the command line.

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.


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 ~/symbian-sdks/s60_30/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 -password mypassword -dname "CN=Joe Bloggs OU=Development OR=Acme Ltd CO=GB EM=noone@nowhere.com" 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 Storsj
martin@martin.st

