
========================================
STLport README for eMbedded Visual C++ 4
========================================

by: Zdenek Nemec, zero@mapfactor.com, last edited 2005-10-17

============
Introduction
============
This document should provide step-by-step guidance for installing, testing and using the STLport library under Windows CE .NET 4.x
(aka Windows Mobile 2003 aka Pocket PC 2003).
For any further comments or questions visit the STLport mailing lists
http://stlport.sourceforge.net/Maillists.shtml or forums
https://sourceforge.net/forum/?group_id=146814

=============
Prerequisites
=============
To build and use the STLport you will need following tools and libraries:
 - eMbedded Visual C++ 4.0 SP4
 - Microsoft RTTI patch, to enable C++ exception handling, available at http://support.microsoft.com/default.aspx?scid=kb;[LN];830482
 - lastest CVS version of the STLport, use info from page 'http://stlport.sourceforge.net/CVS.shtml' to get it

================
Building STLport
================
First, make sure that the RTTI patch is properly installed if required for your SDK - not all SDKs come without builtin support for C++ RTTI.

Second, open command line and set proper system variables.
This can be done by using batch files under your 'eMbedded Visual C++' directory(use either WCEemulator.BAT if you want to build STLport for the emulator or WCEARMV4.BAT if you intend to aim an ARM device).
NOTE: If you are using Microsoft's batch files to set system variables check if both WCEROOT and SDKROOT vars are set to correct locations. example:
WCEROOT=C:\Program Files\Microsoft eMbedded C++ 4.0
SDKROOT=C:\Program Files\Windows CE Tools

Third, when you are 100percent sure you've set correctly systems variables go to the STLport/build/lib dir and run the configure.bat with
proper -c option (ie. "-c evc4"),
then invoke following command: 'nmake /f nmake-evc4.mak install' to build the library.

If anything goes wrong check if you met all prerequisities and if you set system vars accordingly to the makfile you are using.
At the end of build process you should have some libs installed in STLport/lib/evc4-arm or STLport/lib/evc4-x86 and dynamic libs in STLport/bin directory.

You might want to repeat all those steps if you would like to have both ARM and x86 emulator binaries, just don't forget to do 'nmake /f nmake-evc4.mak clobber' before new build.

Note: MIPS platform is also available for build, but it may not compile or work properly. Use with caution!

===============
Testing STLport
===============
When you successfuly build STLport libs, you should go to STLport/test/unit directory build and run the STLP test suite.
Use 'nmake /f nmake-evc4.mak' and keep in mind that you still have to have proper system variables set!
Once test build has finished upload and run stlp_unit_test.exe to your emulator or device.
Wait for a while (aprox. 2mins) untill all tests are done.
You should see two files next to your binary now.
Check stlp_test.txt for any errors. If all tests passed you are ready to deploy STLport.
If some test fails don't worry and check the STLport forum if it's already reported bug or you have found a new one.

=============
Using STLport
=============
Before you start using STLport you have to set proper include and libraries search paths.
Go to 'Tools'>'Options' menu in your eVC 4.0 and then to 'Directories' tab.
For every platform you want to use STLport add STLport/stlport directory to the FIRST place in 'Include Files'
and STLport/lib directory in 'Library files' section.
When using STLport together with MFC, you have to define _STLP_USE_MFC to properly include and use STLport.
Now you should be ready to use STLport.

By default, exception support is not activated. You can detect this via _CPPUNWIND and activate this via /GX.
Without exception support, e.g. std::bad_alloc is not available, causing compile errors for some code.

Also, there is only one runtime available but the IDE doesn't add the corresponding switch to the command line.
The right switch (selecting a dynamically linked runtime) is IMHO /MD or /MDd. This then also switches STLport to dynamic linking.
Alternatively, you can #define _DLL for your project, which achieves the same but, again IMHO, is a less clean solution.

============
Known issues
============
none
