#ifndef DOXYGEN_SKIP
/* $Id: wince_port.dox 18465 2010-01-07 20:39:16Z mloskot $ */
#endif /* DOXYGEN_SKIP */

/*!
\page wince GDAL for Windows CE

\ref wince_overview<br/>
\ref wince_features<br/>
\ref wince_platforms<br/>
\ref wince_directory<br/>
\ref wince_building<br/>
\ref wince_building_proj4<br/>
\ref wince_building_geos<br/>
\ref wince_help<br/>

\warning *** Currently, GDAL port for Windows CE platform is not actively maintained. If you are interested in providing patches or taking over this project, please write to <a href="http://lists.osgeo.org/mailman/listinfo/gdal-dev/">gdal-dev@lists.maptools.org</a> mailing list. ***

\section wince_overview Overview

This document is devoted to give some overview of the GDAL port for <a href="http://en.wikipedia.org/wiki/Windows_CE">Windows CE</a> operating system.

\section wince_features Features

Currently, from version <a href="http://www.gdal.org/dl/gdal140.zip">1.4.0</a>, GDAL includes following features for Windows CE platform:

<ul>
<li>CPL library</li>
<li>GDAL and OGR core API</li>
<li>GDAL drivers:
    <ul>
        <li><a href="http://www.gdal.org/frmt_various.html#AAIGrid">AAIGrid</a></li>
        <li><a href="http://www.gdal.org/frmt_dted.html">DTED</a></li>
        <li><a href="http://www.gdal.org/frmt_gtiff.html">GeoTIFF</a></li>
    </ul>
</li>
<li>OGR drivers:
    <ul>
        <li>Generic</li>
        <li><a href="http://www.gdal.org/ogr/drv_csv.html">CSV</a></li>
        <li><a href="http://www.gdal.org/ogr/drv_mitab.html">MITAB</a></li>
        <li><a href="http://www.gdal.org/ogr/drv_shapefile.html">ESRI Shapefile</a></li>
    </ul>
</li>
<li>Unit Test suite (gdalautotest/cpp)</li>
<li>Optional <a href="http://proj.maptools.org/">PROJ.4</a> support</li>
<li>Optional <a href="http://geos.refractions.net/">GEOS</a> support</li>
</ul>

\section wince_platforms Supported Platforms

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

<ul>
<li>Windows CE 3.x
    <ul><li>Pocket PC 2002</li></ul>
</li>
<li>Windows CE 4.x
    <ul><li>Windows Mobile 2003</li></ul>
</li>
<li>Windows CE 5.x
    <ul>
        <li>Windows Mobile 5
        <li>customized versions of Windows CE 5.0
    </ul>
</li>
</ul>

Supported compilers for Windows CE operating system:

<ul>
<li>Microsoft Visual C++ 2005 Standard, Professional or Team Suite Edition</li>
<li>Microsoft eMbedded Visual C++ 4.0

    \note Currently, no project files provided for eVC++ 4.0 IDE

</li>
</ul>


\section wince_directory Content of 'wince' directory

\note Due to problems with removing directories from CVS and missed synchronization of RC branch,
      the 'wince' directory includes a few deprecated project files (see below).<br />
      Please <strong>DON'T USE</strong> them, unless you want to fix them yourself.

Active content:

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


\deprecated Following directories and projects are deprecated. <strong>DON'T USE THEM!</strong>

<ul>
<li>evc4_gdalce_dll</li>
<li>evc4_gdalce_dll_test</li>
<li>evc4_gdalce_lib</li>
<li>evc4_gdalce_lib_test</li>
<li>msvc8_gdalce_lib</li>
<li>msvc8_gdalce_lib_test</li>
<li>wce_test_dll</li>
<li>wce_test_lib</li>
<li>wcelibcex</li>
</ul>


\section wince_building Building GDAL for Windows CE using Microsoft Visual C++ 2005

<ol>

<li>Requirements

<ul>
<li>You need to have installed Visual C++ 2005 Standard, Professional or
Team Suite Edition.</li>
<li>You also need to have installed at least one SDK for Windows CE platform:
    <ul>
    <li>Windows Mobile 2003 Pocket PC SDK</li>
    <li>Windows Mobile 2003 SmartphoneSDK</li>
    <li>Windows Mobile 5.0 Pocket PC SDK</li>
    <li>Windows Mobile 5.0 Smartphone SDK</li>
    </ul>
</li>
<li>Last requirement is the <a href="http://support.microsoft.com/default.aspx?scid=kb;[LN];830482">Run-time Type Information library for the Pocket PC 2003 SDK</a>.</li>
</ul>

</li>

<li>External dependencies

There is only one external dependency required to build GDAL for Windows CE.
This dependency is <a href="http://wcelibcex.sourceforge.net">WCELIBCEX</a> library available to download from:

http://sourceforge.net/projects/wcelibcex

You can download latest release - <a href="http://sourceforge.net/project/showfiles.php?group_id=160411&package_id=180452&release_id=476819">wcelibcex-1.0</a> - or checkout sources directly form SVN. In both cases, you will be provided with project file for Visual C++ 2005.

\note WCELIBCEX is built to Static Library. For details, check README.txt file form the package.

</li>

<li>Download GDAL 1.4.0 release or directly from CVS 

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:

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

</li>

<li>Projects configuration

    <ol>
    <li>Open gdalce_dll.sln project in Visual C++ 2005 IDE

        According to the paths presented in step 3, you should load following file:

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

    </li>

    <li>Add WCELIBCEX project to gdalce_dll.sln solution

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

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

    </li>

    <a name="gdalce_wcelibcex_configure"></a>
    <li>Configure path to WCELIBCEX source:
        <ul>
        <li>Go to View -> Property Manager to open property manager window</li>
        <li>Expand tree below gdalce_dll -> Debug -> gdalce_common</li>
        <li>Right-click on gdalce_common and select Properties</li>
        <li>In Property Pages dialog, under Common Properties, go to User Macros</li>
        <li>In macros list, double-click on macro named as WCELIBCEX_DIR</li>
        <li>According paths assumed in step 3, change the macro value to: \verbatim C:\dev\wcelibcex-1.0\src \endverbatim </li>
        <li>Click OK to apply changes and close the dialog</li>
        </ul>
    </li>

    <a name="gdalce_wcelibcex_dependency"></a>
    <li>Configure <em>wcelibcex_lib.vcproj</em> as a dependency for <em>gdalce_dll.vcproj</em>
        <ul>
        <li>Select gdalce_dll project in Solution Explorer</li>
        <li>Go to Project -> Project Dependencies</li>
        <li>In the 'Depends on:' pane, select checkbox next to wcelibcex_lib</li>
        <li>Click OK to apply and close</li>
        </ul>
    </li>
    </ol>
</li>


<li>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:

\verbatim
C:\dev\gdal-1.4.0\wince\msvc80\gdalce_dll\Pocket PC 2003 (ARMV4)\Debug
\endverbatim

There, you will find following binaries:

<ul>
<li><strong>gdalce.dll</strong> - dymamic-link library</li>
<li><strong>gdalce_i.lib</strong> - import library</li>
</ul>

</li>

</ol>


\subsection wince_building_proj4 Enable PROJ.4 support

PROJ.4 support is optional.

In the CVS repository of PROJ.4, there are available project files for Visual C++ 2005 for Windows CE.

It is recommended to read <em>README.txt</em> file from <em>wince\\msvc80</em> directory in PROJ.4 sources tree.
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.

<ol>

<li>Go to http://proj.maptools.org and learn how to checkout PROJ.4 source from the CVS</li>

<li>Checkout sources to prefered location, for example:

    \verbatim C:\dev\proj \endverbatim

</li>

<li>Add projce_dll.vcproj project to gdalce_dll.sln solution

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

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

</li>

<li>Open Property Manager as described <a href="#gdalce_wcelibcex_configure">here</a>, open Property Page for gdalce_common,
   and edit macro named as PROJ_DIR.
   
   Change value of the PROJ_DIR macro to: 
   \verbatim C:\dev\proj \endverbatim

   Don't close the Property Manager yet.

</li>

<li>Configure path to WCELIBCEX source:
    <ul>
    <li>Go to View -> Property Manager to open property manager window</li>
    <li>Expand tree below projce_dll -> Debug -> projce_common</li>
    <li>Right-click on projce_common and select Properties</li>
    <li>In Property Pages dialog, under Common Properties, go to User Macros</li>
    <li>In macros list, double-click on macro named as WCELIBCEX_DIR</li>
    <li>According paths assumed in step 3, change the macro value to: \verbatim C:\dev\wcelibcex-1.0\src \endverbatim </li>
    <li>Click OK to apply changes and close the dialog</li>
    </ul>
</li>

<li>Follow instructions explained <a href="#gdalce_wcelibcex_dependency">here</a> and add projce_dll.vcproj as a dependency for gdalce_dll.vcproj</li>

<li>Update proj_config.h file:

    Go to <em>C:\\dev\\proj\\src</em> and rename <em>proj_config.h.wince</em> to <em>proj_config.h</em>.

</li>

<li>Ready to build 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:

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

   There, you can find following binaries:

   <ul>
   <li><strong>proj.dll</strong> - dymamic-link library</li>
   <li><strong>proj_i.lib</strong> - import library</li>
   </ul>

   \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.

</li>

<li>After all, put proj.dll to the same directory on device where you copied gdalce.dll and your application which uses GDAL.</li>

</ol>


\section wince_help How can I help?

I'd like to encourage everyone interested in using GDAL on Windows CE devices to help in its development.
Here is a list of what you can do as a contribution to the project:
<ul>
    <li>You can build GDAL for Windows CE and report problems if you will meet any</li>
    <li>You can try to build new OGR drivers</li>
    <li>You can test GDAL/OGR on different Windows CE devices</li>
    <li>You can write sample applications using GDAL/OGR and announce them on the <a href="http://lists.maptools.org/mailman/listinfo/gdal-dev/">GDAL mailing list</a></li>
    <li>If you have found a bug or something is not working on the Windows CE, please report it on the <a href="http://bugzilla.remotesensing.org">GDAL's Bugzilla</a>
</ul>

<p>There is also <em>wince\\TODO</em> file where you can find list of things we are going to do.</p>

<p>If you have any comments or questions, please sent them to <a href="http://lists.osgeo.org/mailman/listinfo/gdal-dev/">gdal-dev@lists.maptools.org</a> mailing list.</p>

\htmlonly
<p>
$Id: wince_port.dox 18465 2010-01-07 20:39:16Z mloskot $
</p>
\endhtmlonly

*/