# Copyright (c) 2010 Symbian Foundation Ltd

# This component and the accompanying materials are made available

# under the terms of the License "Eclipse Public License v1.0"

# which accompanies this distribution, and is available

# at the URL "http://www.eclipse.org/legal/epl-v10.html".

#

# Initial Contributors:

# Mike Kinghan, mikek@symbian.org, for Symbian Foundation Ltd - initial

# contribution.

== Contents ==

==============

- Intro

- Strategy for building this package

- Preparing to build this package on Linux

- Preparing to build this package on Windows

- Pushing changes to this package repo

- Patch files for the upstream package

== Intro ==

===========

This README describes the status quo at a point in time and it may be out of

date. See also the files TODO and NEWS for possibly more current information.

This README will be updated from time to time.

This package is a branch from the Symbian Build package

(http://developer.symbian.org/oss/MCL/sftools/dev/build) at Mercurial revision

mentioned in the file baseline.txt. The Build package "provides everything you

need to build the Symbian platform." This branch is work-in-progress toward

enabling those tools to build without problems and run correctly on a

conventional GNU/Linux host, as well Windows hosts.

It fixes the upstream package so that:-

* All targets will build without errors or warnings on a GNU/Linux host using

the GCC 4.4.x toolchain and Standard C++ Library.

* All targets will build without errors or warnings on a Windows host using the

Mingw GCC 3.4.x toolchain Standard C++ Library, from a Symbian PDT 1.6

installation.

(The Raptor test-suite targets are skipped, and there is one unimportant

target export target that cannot be built. This is the sbsv2guide

target, which merely exports documentation for Raptor. It cannot be fixed

because the documentation is not present in the upstream package at the branched

revision, bug #2607.)

These fixes *do not* suffice to make all the tools fit for purpose on both Linux

and Windows. That requires more work, which you are invited to undertake and

conrtibute to this package. See the TODO and NEWS files.   

== Strategy for building this package ==

========================================

The strategy for building this package on Linux was:

* Build Raptor, using the native GCC 4.4 toolchain and Standard Library.

* Configure Raptor to use the native GCC toolchain and Standard Library, and

compile according to the C++0x language standard.

* Build the remaining targets conventionally using Raptor.

* Fix the compilation errors and warnings that appeared in this environment in a

way that is proved portable to the Windows build.

The strategy for building the package on Windows was:

* Install PDT 1.6 to get Raptor, with the Mingw GCC 3.4 toolchain and Standard

Library

* Configure Raptor to use the Mingw Standard Library.

* Build the targets, except Raptor itself, conventionally using Raptor.

* Fix the compilation errors and warnings that appeared in this environment in a

way that is proved portable to the Linux build.

The Windows and Linux fix/build cycles were alternated iteratively until both

were error free. The Windows build was performed solely as a portability check,

since all the tools in the package are provided for Windows in the PDT. The

Windows build did not include the building of Raptor itself, since nothing

needs fixed to build Raptor.

For both Linux and Windows, the upstream Raptor configuration was amended to

make GCC invoke the Standard Library installed with the toolchain, and not the

retro STLPort implementation that is included in PDKs and which GCC is

configured to use by default. The code dependencies on this STLPort library are 

superficial and are fixed.

If you contribute to this package, *please ensure your preverse portability

between Windows and Linux*

== Preparing to build this package on Linux ==

==============================================

* Install the host GCC toolchain, if not already present.

* Install preqrequisities for building Raptor.

  - bison

  - libncurses & its headers

  - libbz2 & its headers

* Install the boost libraries and their headers. The upstream package bundles

a defective copy of the boost libraries v1.39 for building the imgtools/imglib

target. The headers of this copy compile for Windows (with one small fix)

but are broken for Linux, so the Linux build is fixed to expect boost libraries

from the system. v1.40 is OK. (v1.35 is too old)

* Install libxml2 and its headers. These are also bundled with the upstream

package for building the imgtools/imgcheck target, but there is no target that

exports them so they are not found by the imgcheck build.

* N.B. On a 64-bit host, you must install the 32-bit variants of the boost and libxml2

libraries. Raptor is built to the host's native wordsize, but all the targets

that are built with Raptor must be 32-bit for compatibility with epoc32 APIs.

* Clone, copy or extract this package into a directory that is going to be your

EPOCROOT for Raptor builds.

* Browse to the Symbian Developer website, http://developer.symbian.org

* Navigate: Tools & Kits -> Download the Symbian^3 kits.

* This package is built using Symbian headers from PDK 3.0.i. If that is not the

current PDK listed under Downloads, then click "Previous releases" and navigate

to the download page for PDK 3.0.i.

* Download the following 3 zip archives from PDK 3.0.i and extract them into

your EPOCROOT directory:

  - binaries_epoc.zip, 

  - binaries_epoc_sdk.zip 

  - tools_epoc.zip

* Consult the README-LINUX file in the subdirectory cross-plat-dev-utils.

== Preparing to build this package on Windows ==

================================================

* Browse to the Symbian Developer website, http://developer.symbian.org

* Navigate: Tools & Kits -> Download the PDT

* For Windows, this package is built using Raptor 2.12.1 in PDT 1.6 If 1.6 is

not the current PDT listed under Downloads, then click "Previous releases" and

navigate to the download page for PDT 1.6.

* Download and install PDT 1.6

* Clone, copy or extract this package into a directory that is going to be your

EPOCROOT for Raptor builds.

* Browse to the Symbian Developer website, http://developer.symbian.org

* Navigate: Tools & Kits -> Download the Symbian^3 kits.

* This package is built using Symbian headers from PDK 3.0.i. If that is not the

current PDK listed under Downloads, then click "Previous releases" and navigate

to the download page for PDK 3.0.i.

* Download the following 3 zip archives from PDK 3.0.i and extract them into

your EPOCROOT directory:

  - binaries_epoc.zip, 

  - binaries_epoc_sdk.zip 

  - tools_epoc.zip

* Consult the README-WINDOWS file in the subdirectory cross-plat-dev-utils.

== Pushing changes to the package repo ==

=============================================

The Raptor build generates a very large volume of files that are not in the

package repo (http://developer.symbian.org/oss/MCL/sftools/dev/linux_build).

If you build Raptor, then you need to remove all of these files before

pushing any other changes to the package repo. Use the script

cross-plat-dev-utils/deepclean_raptor.pl to do this (clean_raptor.pl is not

sufficient). Then remember that you will need to rebuilt Raptor after you

have pushed. 

== Patch files for the upstream package ==

==========================================

In the directory cross-plat-dev-utils/patch-files/diffs you will find one or

more files with names like 'patch-dddddddddddd.patch', for digits 'd'.

The patch file 'patch-dddddddddddd.patch' shows the diffs between the upstream

package (http://developer.symbian.org/oss/MCL/sftools/dev/build) at revision

dddddddddddd and this package as baselined on that upstream revision. Only

diffs relevant to changing the upstream package are included.

You can also apply this patch file to the upstream package at revision

dddddddddddd to make it the same as the revision of this package from which it

was diffed. You can use the utility cross-plat-dev-tools/patch_upstream.pl to

do this.