$Id$
=============================================================================
 GDAL port for Window CE
 Originally ported by Mateusz Loskot, mateusz@loskot.net
=============================================================================

GDAL 1.4.0 includes following features for Windows CE platform:

1. CPL library
2. GDAL and OGR core API
3. GDAL drivers:
   -  AAIGrid
   -  DTED
   -  GeoTIFF
4. OGR drivers
   - CSV
   - Generic
   - MITAB
   - ESRI Shapefile
5. Unit Test suite (gdalautotest/cpp) 
6. Optional PROJ.4 support
7. Optional GEOS support


GDAL for Windows CE has been tested on following versions of Windows CE:

1. Windows CE 3.x
   - Pocket PC 2002
2. Windows CE 4.x
   - Windows Mobile 2003
3. Windows CE 5.x
   - Windows Mobile 5
   - customized versions of Windows CE 5.0

Supported compilers for Windows CE operating system:

1. Microsoft Visual C++ 2005 Standard or Professional
2. Microsoft eMbedded Visual C++ 4.0 (NOTE: Currently, no project files provided)


=============================================================================
 Content of gdal\wince directory:
=============================================================================

Active content:

- msvc80 - project for Visual C++ 2005 to build GDAL DLL for Windows CE
- README - the file you're currently reading
- TODO   - planned and requested features 

=============================================================================
 Building GDAL for Windows CE using Microsoft Visual C++ 2005
=============================================================================

1. Requirements

You need to have installed Visual C++ 2005 Standard, Professional or
Team Suite Edition.

You also need to have installed at least one SDK for Windows CE platform:

- Windows Mobile 2003 Pocket PC SDK
- Windows Mobile 2003 SmartphoneSDK
- Windows Mobile 5.0 Pocket PC SDK
- Windows Mobile 5.0 Smartphone SDK

If you are going to build against Windows Mobile 2003 SDK, there is one more 
requirement. You have to install the Run-time Type Information library
for the Pocket PC 2003 SDK

http://support.microsoft.com/default.aspx?scid=kb;[LN];830482

2. External dependencies

There is only one external dependency required to build GDAL for Windows CE.
This dependency is WCELIBCEX library available to download from the SourceForge.net:

http://sourceforge.net/projects/wcelibcex

You can download latest release - wcelibcex-1.0 - or checkout sources directly form SVN.
In both cases, you will be provided with project file for Visual C++ 2005.
WCELIBCEX is built to Static Library. For details, check README.txt file form the package.

3. Download GDAL 1.4.0

Go to http://www.gdal.org/download.html and download ZIP package with GDAL 1.4.0.
You can also checkout sources directly from SVN.

For this guidelines, I assume following directories structure:

C:\dev\gdal-1.4.0
C:\dev\wcelibcex-1.0

4. Projects configuration

a) Open gdalce_dll.sln project in Visual C++ 2005 IDE.
   According to the paths presented in step 3, you should load following file:

   C:\dev\gdal-1.4.0\wince\msvc80\gdalce_dll\gdalce_dll.sln

b) Add WCELIBCEX project to gdalce_dll.sln solution:

   Go to File -> Add -> Existing Project, navigage and open following file:

   C:\dev\wcelibcex-1.0\msvc80\wcelibcex_lib.vcproj 

c) Configure path to WCELIBCEX source:

   - Go to View -> Property Manager to open property manager window.
   - Expand tree below gdalce_dll -> Debug -> gdalce_common.
   - Right-click on gdalce_common and select Properties.
   - In Property Pages dialog, under Common Properties, go to User Macros
   - In macros list, double-click on macro named as WCELIBCEX_DIR
   - Change the macro value to C:\dev\wcelibcex-1.0\src, according paths assumed in step 3
   - Click OK to apply changes and close the dialog

d) Configure wcelibcex_lib.vcproj as a dependency for gdalce_dll.vcproj

   - Select gdalce_dll project in Solution Explorer
   - Go to Project -> Project Dependencies
   - In the 'Depends on:' pane, select checkbox next to wcelibcex_lib 
   - Click OK to apply and close

5. Now, you are ready to build GDAL for Windows CE

   Go to Build and select Build Solution

   After a few minutes, you should see GDAL DLL ready to use.
   For example, when Pocket PC 2003 SDK is used and Debug configuration requested,
   all output files are located under this path:
   
   C:\dev\gdal-1.4.0\wince\msvc80\gdalce_dll\Pocket PC 2003 (ARMV4)\Debug

   where you can find following binaries:

   gdalce.dll - dymamic-link library
   gdalce_i.lib - import library


============================================
 Optional configuration
============================================

Currently, configuring PROJ.4 and GEOS support is not easy, but feasible.
In near future, I'll prepare some best practice and try to make it as easy as possible.
On the CVS of PROJ.4, there are project files for Visual C++ 2005 for Windows CE available.
Unfortunately, no project files for Windows CE are provided for GEOS, but I'll try to change it very soon.

1. Enable PROJ.4 support

It is recommended to read README.txt file in C:\dev\proj\wince\msvc80.
There, you will find instructions how to build PROJ.4 without attaching its project to gdalce_dll.sln.
Then you can just add proj.dll and proj_i.lib to linker settings of gdalce_dll.vcproj project.

Below, you can find instructions how to add projce_dll.vcproj project
directly to gdalce_dll.sln and build everything together.

a) Go to http://proj.maptools.org and learn how to checkout PROJ.4 source from the CVS

b) Checkout sources to prefered location, for example C:\dev\proj

c) Add projce_dll.vcproj project to gdalce_dll.sln solution

   Go to File -> Add -> Existing Project, navigage and open following file:

   C:\dev\proj\wince\msvc80\projce_dll\projce_dll.vcproj 

d) Open Property Manager as described in point 4.c) above, open Property Page for gdalce_common,
   and edit macro named as PROJ_DIR.
   
   Set the PROJ_DIR value to C:\dev\proj

   Don't close the Property Manager yet.

e) Configure path to WCELIBCEX source:

   - Go to View -> Property Manager to open property manager window.
   - Expand tree below projce_dll -> Debug -> projce_common.
   - Right-click on projce_common and select Properties.
   - In Property Pages dialog, under Common Properties, go to User Macros
   - In macros list, double-click on macro named as WCELIBCEX_DIR
   - Change the macro value to C:\dev\wcelibcex-1.0\src
   - Click OK to apply changes and close the dialog

f) Follow instructions explained in step 4.d) and add projce_dll.vcproj as a dependency for gdalce_dll.vcproj.

g) Update proj_config.h file:

   Go to C:\dev\proj\src and rename proj_config.h.wince to proj_config.h

h) Now, you are ready to rebuild GDAL for Windows CE

   Go to Build and select Build Solution

   Similarly to explanation above in step 5 for GDAL, binaries for PROJ.4 for Windows CE
   can be found here:

   C:\dev\proj\wince\msvc80\projce_dll\Pocket PC 2003 (ARMV4)\Debug

   where you can find following binaries:

   proj.dll - dymamic-link library
   proj_i.lib - import library

   NOTE: PROJ.4 binaries for Windows CE do not include 'ce' in names.
         This is due the fact GDAL uses fixed proj.dll name to find and
         link dynamically with PROJ.4 DLL.

i) After all, put gdalce.dll and proj.dll to the same directory where your
   application which uses GDAL is installed on device.


2. Enable GEOS support

TODO - I'm going to publish VC++ project files soon, then this points will be updated.


=============================================================================
 How can I contribute?
=============================================================================

- you can build GDAL for Windows CE and report problems if any
- you can try to port new drivers
- you can test GDAL on different Windows CE devices
- you can write sample applications using GDAL
- if you have found a bug, please report it

=============================================================================
 How can I report a bug?
=============================================================================

Visit Bugzilla on http://bugzilla.remotesensing.org

Bug Writing Guidelines:
http://bugzilla.remotesensing.org/page.cgi?id=bug-writing.htm

=============================================================================
 Thanks to:
=============================================================================

- Frank Warmerdam for GDAL/OGR and priceless support he provide me
- Taxus SI Ltd. from Poland for their great support
- Users from IRC #gdal channel
- All users, testers and contributor

=============================================================================
Questions?
=============================================================================

Mailing list: gdal-dev@lists.maptools.org
You can catch me on mateusz@loskot.net or ping mloskot on the #gdal IRC channel.