==================================================
STLport README for Borland C++ compilers.
==================================================

by: Francois Dumont, dums@stlport.com, last edited 20 May 2006

============
Introduction
============
This document describes how STLport can be compiled and used with
Borland compilers.

For any further comments or questions visit STLport mailing lists
http://stlport.sourceforge.net/Maillists.shtml or forums
https://sourceforge.net/forum/?group_id=146814

=============
Prerequisites
=============
To build and use STLport you will need following tools and libraries:
 - Borland C++ compiler package 5.5.1 or higher version.

    In order to build STLport the Borland compiler and linker have to
  be correctly configurated too. That is to say:

    * For the Borland compiler bcc32:

    In Borland's 'bin' directory (same directory as bcc32.exe), create a
  bcc32.cfg file containing the compiler option giving it the path to
  native Borland headers:

	-I%BORLAND_PATH%\BCC55\include

    * For the resource compiler brcc32:

    Create an environment variable INCLUDE containing path to native Borland
    headers and especially the windows.h file

	set INCLUDE=%BORLAND_PATH%\BCC55\include

    * For the Borland linker ilink32:

    You need to give path to both the Borland libs and Borland PSDK libs.
    For that you have to create, in the same directory as ilink32.exe, a
    configuration file, ilink32.cfg, that contains:

	-L%BORLAND_PATH%\BCC55\lib;%BORLAND_PATH%\BCC55\lib\PSDK

 - A GNU make tool. You can get one from www.mingw.org or www.cygwin.com.
   See README.mingw or README.cygwin for additional informations.

===================
Configuring STLport
===================
  This is intended to be an optional step, if you want to use default
configuration simply jump to next chapter 'Building STLport'. Open a console
and go to the STLport build/lib folder. Run

	configure --help

  This command will present you the different available build options. Just follow
the instructions to set STLport configuration according your needs. For example,
to set the typical configuration for most Borland compilers, run

    configure -c bcc

================
Building STLport
================
  This is a step by step description of the actions to take in order to build
and install the STLport libraries:

1. Open a console, you can use a Msys, Cygwin or Windows console.

2. Go to the STLport build/lib folder:
	cd C:\STLport\build\lib

3. Run the following command:
	make -fbcc.mak install

	Where 'make' is the GNU make utility you have installed. The name of
GNU make utility may differ, such as 'mingw32-make'.  -f is a make option
telling it which makefile to use. You have of course to choose the
appropriate makefile for your compiler, 'bcc.mak' in our case.

	Once the command returns you will have all the necessary import libraries
in STLport's 'lib' folder and DLLs in STLport's 'bin' folder.  For a
description of the generated libraries check the FAQ file in the 'doc' folder.
For a quick start guide to the STLport make system, see the README file in the
'build/lib' folder.

===============
Testing STLport
===============
You can use the unit tests to verify STLport behaves correctly. Change into
STLport's 'build/test/unit' folder and type:

  make -fbcc.mak install

This will build and install the unit tests with STLport dynamic libraries.
Once the unit tests are built you just need to run them.  They can be found
in STLport's bin, bin-g or bin-stlg folders.  To rebuild the unit tests
with STLport static libraries, type:

  make -fbcc.mak clean
  make -fbcc.mak install-static

=============
Using STLport
=============
Adjust your include and link paths in Borland IDE or in the command line config
files. In the include files add the path to STLport's 'stlport' folder. Make sure
it is the first directory listed there. Add STLport's 'lib' folder for the library
files (order of paths doesn't matter here).

Now you should be ready to use STLport.

============
Known limitations
============

1. If you extend a locale facet based on a Standard facet definition you will
have to grant your own facet id defition. Ex extracted from
test/unit/fstream_test.cpp:

#include <locale>

using namespace std;

struct my_state {
  char dummy;
};

struct my_traits : public char_traits<char> {
  typedef my_state state_type;
  typedef fpos<state_type> pos_type;
};

class my_codecvt : public codecvt<char, char, my_state>
{};

// Mandatory locale facet id definition:
template <>
locale::id codecvt<char, char, my_state>::id;

2. If you get a linker memory error, e.g. LME351, it probably means that full
source debugging is enabled and Borland's .TDS file has exceeded the memory
capacity of Borland's linker (ilink32.exe).  To resolve this error, check
Borland's website for the latest patch for ilink32.exe.  In the alternative,
disable full source debugging in build\Makefiles\gmake\bcc.mak by deleting
the -v option in the OPT settings.

3. For "'uname' is not recognized . . .", see "Configuring STLport" above.

The cygwin platform is used to build STLport with different compilers.

- gcc (native compiler):

  Makefile : gcc.mak

  Notes:

    1. Static builds (archive)

    If you use the static version of the STLport libraries you have
  to define the _STLP_USE_STATIC_LIB macro in order to have your
  executable linked correctly.

    2. Link

    Under this platform STLport is complete replacement for libstdc++.
  It means that when you were linking with libstdc++ (-lstdc++) you only
  have to replace it with STLport (-lstlport.5.2 for instance). However
  default gcc behavior is to automatically link libstdc++ and a number of
  other system libs. To avoid this behavior you have to use the -nodefaultlibs
  compiler option and explicitely give all libraries by yourself. See build of
  unit tests to see what library you might need, here is the list when this
  note was written:

  without -mnocygwin option:

    -lstlportg.5.2 -lgcc -lm -lc -lpthread -lkernel32

  with -mno-cygwin option:

    -lstlportg.5.2 -lgcc -lmingw32 -lmingwex -lmsvcrt -lm -lmoldname
    -lcoldname -lkernel32

    3. No cygwin

    To build STLport libraries that do not depend on cygwin1.dll
  making them freely redistributable pass the following option to
  the configure script:

  ./configure --with-extra-cflags=-mno-cygwin --with-extra-cxxflags=-mno-cygwin

- Borland C++ compiler

==================================================
STLport README for Digital Mars C++ compilers.
==================================================

Build of STLport with Digital Mars C++ compiler is very similar
to the one for Microsoft Visual Studio compiler (see README.msvc).

Below are some additional hints. [DMC users are encouraged to
contribute additional information.]

=============
Prerequisites
=============

 - Digital Mars C++ 8.49 or above

 - A GNU environment with make tool. Prefer MinGW/MSys to Cygwin because the
   latter contains a link command that is also the name of the Digital Mars linker
   and you might experiment collision between both commands.
   See README.mingw for additional information.

===================
Installing STLport
===================

 - STLport directory can be almost anywhere EXCEPT native dm\include directory.

===================
Configuring STLport
===================

 - In a console window go to the STLport build\lib folder. Run

	  configure -c dmc

================
Building STLport
================

 - To build STLport libraries:

    cd [STLport dir]\build\lib
    [mingw32-make] -f dmc.mak install

 - To build STLport (dynamic) unit tests:

    cd [STLport dir]\build\test\unit
    [mingw32-make] -f dmc.mak install

============
Known issues
============

1. typeinfo.h

  DMC forces inclusion of typeinfo.h header at the begining of any
translation unit. This breaks the STLport include schema, especially
when building the library. As a workaround STLport typeinfo.h simply
include native DMC header not performing any internal STLport work as
importing things to STLport namespace. As a result typeinfo.h should
never be reference in user code, as it is neither a C nor a C++ header
this is not considered as a major limitation. The C++ Standard header
is typeinfo.

2. link.exe and lib.exe

  STLport makefiles for DMC use dm_link and dm_lib instead of link and lib to
avoid conflicts with other vendors' linkers and archivers.  To build STLport
with DMC, please copy or rename the following files:

  copy dm\bin\link.exe dm\bin\dm_link.exe
  copy dm\bin\lib.exe dm\bin\dm_lib.exe

3. Free online version.

  If DMC's free online version reports compiler or linker errors, the
solution may be in a free online CD update.  Download and unzip all free
CD patches for versions 8.30 and above, in consecutive order, overwriting
previous files. Then install free online version 8.49 or above, overwriting
previous files.

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

by: Michael Fink, vividos@users.sourceforge.net, last edited 2005-11-15

============
Introduction
============
This document describes how STLport can be compiled and used with Microsoft
eMbedded Visual C++ 3.

For any further comments or questsion visit STLport mailing lists
http://stlport.sourceforge.net/Maillists.shtml or forums
https://sourceforge.net/forum/?group_id=146814


=============
Prerequisites
=============
To build and use STLport you will need following tools and libraries:
 - eMbedded Visual C++ 3.0
 - latest CVS version of STLport, use info from page
   'http://stlport.sourceforge.net/CVS.shtml' to get it.
   Note that you may have to get a different branch, please check out the
   STLport forum "Announcements" which sourcecode is being worked on.

================
Building STLport
================
Note: if you don't plan to use the iostreams part of STLport (via the define
_STLP_NO_IOSTREAMS), you don't have to build the library. You can skip straight
to the "Using STLport" section.

If you want to compile for the Pocket PC 2002 SDK (which in most cases you want)
be sure to set the PLATFORM environment variable to "Pocket PC 2002", e.g. with
this command:

  set PLATFORM=Pocket PC 2002

Open a command line prompt and execute the batch file that sets up compiling
for ARM or x86 processors. These files usually are in a folder like
'C:\Program Files\Windows CE eMbedded Tools\EVC\WCE300\BIN\' and are called
WCEARM.bat and WCEx86.bat. Check if the environment variables are set up
properly after that call. You can also adjust the batch files to have the
PLATFORM variable set automatically.

Go into STLport's 'build\lib' folder and type:

  configure.bat -c evc3

The makefiles are configured with the given settings. Call configure.bat with
the --help option to see all options. The program automatically tells you which
command line to use. If you want to install the libraries, add the "install"
target as follows:

  nmake /fmsvc.mak install

All libraries (debug, stldebug, release) are now built, static and shared
ones. Import libraries (.lib files) are put in the 'lib\evc3-arm' folder, DLLs
are put in the 'bin\evc3-arm' folder. If you use another target platform, the
name of the folder is changed accordingly, e.g. evc3-x86 for emulator files.

Once STLport is built you can decrease the size of the STLport folder by
removing intermediate build files. This is done with the following command:

  nmake /fmsvc.mak clobber

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

===============
Testing STLport
===============
You can use the unit tests to verify STLport behaves correctly. Change into
STLports 'build\test\unit' folder and type:

  nmake /fmsvc.mak install

If you want to build the unit tests for the emulator, you have to reconfigure
STLport with the configure.bat, as described above.

Once the unit tests are built, upload the binary (found in the 'bin\evc3-arm'
folder) to your device or emulator and start it (the test runs for about 30
seconds, depending on the speed of the device). The file 'stlp_test.txt' is
created in the root folder of the device, which contains the unit test
results. It should report no errors.

=============
Using STLport
=============
Adjust your include and link paths in eVC3 in 'Tools -> Options -> Directories'
and add the paths for all platforms and CPUs on which you want to use STLport.
In the include files add the path to STLport's 'stlport' folder. Make sure it
is the first directory listed there. Add STLport's 'lib\evc3-arm' or
'lib\evc3-x86' (depending on what target you use) folder for the library files
(order of paths doesn't matter here).

There are some preprocessor defines that control usage of the STLport in evc3
projects:

Define the symbol _STLP_USE_STATIC_LIB when you want to statically link against
STLport. The linker will remove unused classes and methods then, saving some
space in the executable.

If you don't want to use the iostreams part of the library, you can specify the
define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the
library.

STLport uses automatic linking to find the proper .lib file. If you want to see
what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK.
When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you
have to specify the proper .lib file in the Project Settings, on the "link" tab.
The .lib names have the following syntax:

   stlport(d|stld)[_static].<STLport-Version>.lib

Examples:

   stlport_static.5.0.lib - static release version, Version 5.0.0
   stlportd_50.lib - dll debug version, Version 5.0.0

Note that usage of the _STLP_DEBUG mode is currently not recommended for
eMbedded Visual C++ builds using the ARM compiler, due to a compiler bug.

When using STLport together with MFC, be sure to include the MFC headers first,
then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly
recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in
your project settings or in stlport/stl/config/user_config.h.

Now you should be ready to use STLport.

============
Known issues
============
 - Unit Tests in _STLP_DEBUG mode (target 'stldbg-shared') fails in
   __stl_debug_engine::_M_detach() for several tests due to unknown reasons.
   A compiler bug in the ARM compiler is suspected.
   There is currently no workaround for this bug. It is recommended to not use
   _STLP_DEBUG mode.

 - Resource compiler issue:

    The resource compiler is not a C++ compiler, it is a compiler that translates
  resource files, i.e. files that describe dialogs, strings, version information
  and other parts of the GUI on MS Windows systems.

    The problem is that it includes files from the C/C++ include path, and
  STLport uses mechanisms the resource compiler can't handle, e.g. using macro
  names longer than 31 characters.

    The workaround is to guard all affected headers (stdio.h, string.h, stdarg.h,
  stdlib.h, ctype.h) against this. The resource compiler is detected by the
  macro RC_INVOKED.

 - See also README.evc4 issues.

========================================
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
 - an SDK for your target platform with RTTI support

================
Building STLport
================
First, make sure that RTTI is available. Not all SDKs that come with eVC4 also include
the necessary libs, but there is a patch for the PPC2003 SDK, available at
http://support.microsoft.com/default.aspx?scid=kb;[LN];830482.

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 /fmsvc.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
e.g. both ARM and x86 emulator binaries, just don't forget to do
'nmake /fmsvc.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 /fmsvc.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) until 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
=============
Setting up the IDE:
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.

Setting up projects:
When using STLport together with MFC, you have to define _STLP_USE_MFC to properly include and 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
============
- The compilers that come with eVC4 are almost bug-to-bug compatible with
the one from VC6, so most workarounds for that compiler apply here, too.

- There is a bug in the MIPS compiler that comes with eVC4 which only surfaces
under certain conditions:
 * in release mode with global optimizations on (#pragma optimize("g", on))
 * a baseclass has (at least) two pointer members
 * a derived class adds no data members
 * the derived class' cctor defers to the basclass' compiler-generated cctor
 * it is passed as template parameter to a function
The smallest testcase I could come up with is this:
	struct base {
		void* ptr1;
		void* ptr2;
	};
	struct derived: public base {
		derived() {}
		derived(const derived& __x): base(__x) {}
	};

	template<typename SomeType> void function( SomeType st1, SomeType st2) {}

	struct test {
		derived tmp;
		~test() { function(tmp, tmp); }
	};
	test test;
..which causes an internal compiler error. Removing the base::ptr1, adding data
to derived, making function() a normal function, or turning off optimization
(#pragma optimize("g", off)) all causes the code to compile. This bug affects
iterators of deque and vector<bool>.

- Because of interdependancy between STLport and native Standard library headers
STLport headers should always be included first in your translation unit (.cpp
file). That is to say that:

//Wrong headers order:
#include <windows.h>
#include <cstdlib>

// Correct headers order
#include <cstdlib>
#include <windows.h>

setup VC8 for CE:
------------------

- VC8 doesn't have any setup batchfiles that prepare the environment for compiling
with CE. You can take those from eVC4 and adapt them or write your own. This snippet
should get you going:

  rem you need to adapt at least these three
  set OSVERSION=WCE500
  set PLATFORM=MY_OWN_PLATFORM
  set TARGETCPU=MIPSII

  rem the compiler is always cl.exe, different compilers are in different paths
  set CC=cl.exe
  rem obviously, these need to be adjusted to where you installed VS2005 and the SDKs
  set VSINSTALLDIR=C:\Programme\Microsoft Visual Studio 8
  set SDKROOT=C:\Programme\Windows CE Tools

  set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_mips;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
  set PLATFORMROOT=%SDKROOT%\%OSVERSION%\%PLATFORM%

  rem add libs and includes from the SDK
  set INCLUDE=%PLATFORMROOT%\include\%TARGETCPU%;%PLATFORMROOT%\MFC\include;%PLATFORMROOT%\ATL\include
  set LIB=%PLATFORMROOT%\lib\%TARGETCPU%;%PLATFORMROOT%\MFC\lib\%TARGETCPU%;%PLATFORMROOT%\ATL\lib\%TARGETCPU%

  rem add libs that came with VC8
  rem Note: there are more libs and includes under ce\atlmfc, not sure if these are needed.
  set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%


- The snippet below can be used to build STLport for Pocket PC 2003 (using the
  Pocket PC 2003 SDK shipped with Visual Studio 2005, this is the SDK used when
  compiling programs from within the IDE):

  set OSVERSION=WCE420
  set PLATFORM=POCKET PC 2003
  set TARGETCPU=ARMV4

  rem the compiler is always cl.exe, different compilers are in different paths
  set CC=cl.exe

  rem obviously, these need to be adjusted to where you installed VS2005
  set VSINSTALLDIR=C:\Program Files\Microsoft Visual Studio 8
  set SDKROOT=%VSINSTALLDIR%\SmartDevices\SDK

  set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_arm;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
  set PLATFORMROOT=%SDKROOT%\PocketPC2003

  rem add libs and includes from the SDK
  set INCLUDE=%PLATFORMROOT%\include
  set LIB=%PLATFORMROOT%\lib\%TARGETCPU%

  rem add libs that came with VC8
  set INCLUDE=%INCLUDE%;%VSINSTALLDIR%\VC\ce\atlmfc\include
  set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%;%VSINSTALLDIR%\VC\ce\atlmfc\lib\%TARGETCPU%


You should now be able to run cl.exe for the target you expected.

- The cross compilers of VC8 are the same version as for the native target, i.e. MSC14.

- The cross compiler for MIPS has the same bug as mentioned in doc/README.evc4 and
the same workaround applies. However, using 'whole program optimization', it results
in an error in the link phase.

- In order for STLport to recognize which target you are compiling for, you need to have
some macros defined, e.g. for the target architecture. The compilers do that partially on
their own, but not sufficiently. Therefore, STLport requires these defines:

 -- These are generally set for CE:
  _UNICODE;UNICODE;_WIN32;WIN32;UNDER_CE;WINCE;
 -- This one uses an environment variable to set the CE version:
  _WIN32_WCE=$(CEVER);
 -- These are used to help STLport recognise the target architecture:
  $(ARCHFAM);$(_ARCHFAM_);$(INSTRUCTIONSET)
 Note that the instructionset is not strictly needed for x86 but definitely for ARM. It
 doesn't hurt for x86 though, so I'd always set these in any new project.
 -- For release builds:
  NDEBUG;
 -- For debug builds:
  DEBUG;_DEBUG;
 -- For debug builds with additional STLport diagnostics:
  DEBUG;_DEBUG;_STLP_DEBUG;
 -- For MFC applications:
  _AFXDLL;

- Further settings:
 Code generation: Multithreaded [Debug] DLL
 Language: enable RTTI
 Optimization: maximise speed and enable whole program optimization for release builds

- Linker settings:
 Ignore specific libraries: libc.lib;libcd.lib
 Commandline: /SUBSYSTEM:WINDOWSCE
 Optimisation: /LTCG for release builds

- Resource compiler:
 Define: UNDER_CE;WINCE;_WIN32_WCE=$(CEVER)

setup VC9 for CE:
------------------

- VC9 doesn't have any setup batchfiles that prepare the environment for compiling
with CE. You can take those from eVC4 and adapt them or write your own. This snippet
should get you going:

  rem you need to adapt at least these three
  set OSVERSION=WCE500
  set PLATFORM=MY_OWN_PLATFORM
  set TARGETCPU=MIPSII

  rem the compiler is always cl.exe, different compilers are in different paths
  set CC=cl.exe
  rem obviously, these need to be adjusted to where you installed VS2008 and the SDKs
  set VSINSTALLDIR=C:\Programme\Microsoft Visual Studio 9.0
  set SDKROOT=C:\Programme\Windows CE Tools

  set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_mips;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
  set PLATFORMROOT=%SDKROOT%\%OSVERSION%\%PLATFORM%

  rem add libs and includes from the SDK
  set INCLUDE=%PLATFORMROOT%\include\%TARGETCPU%;%PLATFORMROOT%\MFC\include;%PLATFORMROOT%\ATL\include
  set LIB=%PLATFORMROOT%\lib\%TARGETCPU%;%PLATFORMROOT%\MFC\lib\%TARGETCPU%;%PLATFORMROOT%\ATL\lib\%TARGETCPU%

  rem add libs that came with VC9
  rem Note: there are more libs and includes under ce\atlmfc, you need to add these
  rem instead of the ones in the SDK if you want to use the newer version of ATL/MFC.
  set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%


- The snippet below can be used to build STLport for Pocket PC 2003 (using the
  Pocket PC 2003 SDK shipped with Visual Studio 2008, this is the SDK used when
  compiling programs from within the IDE):

  set OSVERSION=WCE420
  set PLATFORM=POCKET PC 2003
  set TARGETCPU=ARMV4

  rem the compiler is always cl.exe, different compilers are in different paths
  set CC=cl.exe

  rem obviously, these need to be adjusted to where you installed VS2008
  set VSINSTALLDIR=C:\Program Files\Microsoft Visual Studio 9.0
  set SDKROOT=%VSINSTALLDIR%\SmartDevices\SDK

  set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_arm;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
  set PLATFORMROOT=%SDKROOT%\PocketPC2003

  rem add libs and includes from the SDK
  set INCLUDE=%PLATFORMROOT%\include
  set LIB=%PLATFORMROOT%\lib\%TARGETCPU%

  rem add libs that came with VC9
  set INCLUDE=%INCLUDE%;%VSINSTALLDIR%\VC\ce\atlmfc\include
  set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%;%VSINSTALLDIR%\VC\ce\atlmfc\lib\%TARGETCPU%


You should now be able to run cl.exe for the target you expected.

- The cross compilers of VC9 are the same version as for the native target, i.e. MSC15.

- In order for STLport to recognize which target you are compiling for, you need to have
some macros defined, e.g. for the target architecture. The compilers do that partially on
their own, but not sufficiently. Therefore, STLport requires these defines:

 -- These are generally set for CE:
  _UNICODE;UNICODE;_WIN32;WIN32;UNDER_CE;WINCE;
 -- This one uses an environment variable to set the CE version:
  _WIN32_WCE=$(CEVER);
 -- These are used to help STLport recognise the target architecture:
  $(ARCHFAM);$(_ARCHFAM_);$(INSTRUCTIONSET)
 Note that the instructionset is not strictly needed for x86 but definitely for ARM. It
 doesn't hurt for x86 though, so I'd always set these in any new project.
 -- For release builds:
  NDEBUG;
 -- For debug builds:
  DEBUG;_DEBUG;
 -- For debug builds with additional STLport diagnostics:
  DEBUG;_DEBUG;_STLP_DEBUG;
 -- For MFC applications:
  _AFXDLL;

- Further settings:
 Code generation: Multithreaded [Debug] DLL
 Language: enable RTTI
 Optimization: maximise speed and enable whole program optimization for release builds

- Linker settings:
 Ignore specific libraries: libc.lib;libcd.lib
 Commandline: /SUBSYSTEM:WINDOWSCE
 Optimisation: /LTCG for release builds

- Resource compiler:
 Define: UNDER_CE;WINCE;_WIN32_WCE=$(CEVER)

Build of STLport with Intel C++ compiler for Windows is identical
to the one for Microsoft Visual Studio compiler (see README.msvc).

Known issues:

1. If you have bind your Intel C++ compiler to the Visual Studio 6
install and build your application without the -Qvc6 option you might
experiement linking issue concerning 'std::unexpected' missing symbol.
The reason of this problem is that without -Qvc6, ICL adds necessary
code to invoke std::unexpected function when a raised exception is
different to the one specified in a function prototype. As VC6 library
do not contain this symbol ICL cannot find it anywhere.

  As a workaround, STLport has its own std::unexpected implementation
that you will find in src/dll_main.cpp. ICL is looking for a static
symbol so if you use STLport static lib ICL will use its std::unexpected
implementation but if you use STLport dynamic lib then ICL won't find
it. You only need then to copy/paste the STLport implementation somewhere
in your implementation and ICL will be happy.

  The MinGW GNU make command can be used to build STLport with different
compilers

- gcc (native compiler):

  Makefile : gcc.mak

  Notes:

    1. Static library (archive)

    If you use the static version of the STLport libraries
  you have to define the _STLP_USE_STATIC_LIB macro in order
  to have your executable linked correctly.

    2. Shell

    You will need MSys in order to build STLport.

    Be carefull about what make command you are using. STLport comes with a
  GNU make build system design for unix like platforms, make files have not
  been adapted for the Windows platform. So you have to use the make command
  coming with the MinGW package 'mingw32-make' and not the one coming with MSys
  that is a portage of the GNU make for Windows.

    3. Threading configuration

    STLport libraries are built per default in order to be used in a
  multithreaded environment. Under MinGW it means that we use the '-mthread'
  compiler option. Don't forget to add it to your compiler command line too
  if you want to use STLport libraries. You can also ask for not thread
  safe libraries using the --no-thread configure script option.

    4. Linking

    In this environment STLport is almost complete replacement for libstdc++.
  It means that when you were linking with libstdc++ (-lstdc++) you only have
  to replace it with STLport (-lstlport.5.2 for instance) and with libsupc++
  containing language compiler support (lsupc++). However default gcc
  behavior is to automatically link libstdc++ and a number of other system libs.
  To avoid this behavior you have to use the -nodefaultlibs compiler option and
  explicitely give all libraries by yourself. See build of unit tests to see what
  library you might need, here is the list when this note was written:

    -lstlportg.5.2 -lsupc++ -lgcc_s -lmingw32 -lmingwex -lmsvcrt -lm -lmoldname
    -lcoldname -lkernel32

- Borland C++ compiler:

  Makefile : bcc.mak

- Digital Mars C++ compiler:

  Makefile : dmc.mak

==================================================
STLport README for Microsoft Visual C++ compilers.
==================================================

by: Francois Dumont, dums@stlport.com, last edited 08/02/2005

============
Introduction
============
This document describes how STLport can be compiled and used with Microsoft
Visual C++ 6 SP5. It can also be used for the MSVC++ family.

For any further comments or questsion visit STLport mailing lists
http://stlport.sourceforge.net/Maillists.shtml or forums
https://sourceforge.net/forum/?group_id=146814

=============
Prerequisites
=============
To build and use STLport you will need following tools and libraries:
 - Microsoft Visual C++ 6.0 with at least Service Pack 5 or any higher
 version.

===================
Configuring STLport
===================
In a console window go to the STLport build/lib folder. Run

	configure --help

This command will present you the different available build options. Just follow
the instructions to set STLport configuration according your needs. The only
mandatory configuration is to declare what is the compiler you are going to
use, for MSVC 6 it is:

	configure -c msvc6

================
Building STLport
================
This is a step by step description of the actions to take in order to have
the STLport library built:

1. Open a console window. You can get it executing cmd or command depending
on your Windows OS.

2. Go to MSVC++ Bin directory with a default MSVC6 install it is
	cd "C:\Program Files\Microsoft Visual Studio\VC98\Bin"

3. Run the vcvars32.bat script. This sets the environment variables required
to have the MSVC++ compiler run during the build process. The most important
one is the PATH variable so that you can call the cl.exe command which is the
MSVC++ command line compiler. [You may omit this step, if you chose 'Install paths
to access command-line tools' during Microsoft Visual Studio installation procedure.]

4. Go to the STLport build/lib folder:
	cd C:\STLport\build\lib

5. Run the following command:
	nmake /fmsvc.mak install

	nmake is the make utility from Microsoft. /f is an nmake option
telling it which make file script to use. You have of course to grant the
closer make file to your effective compiler, msvc.mak in our case.

	Once the command returns, you will have all the necessary libraries within
the STLport lib folder. For a description of the generated libraries check the README
file within the src folder.

===============
Testing STLport
===============
You can use the unit tests to verify STLport behaves correctly. Change into
STLports 'build/test/unit' folder and type:

  nmake /fmsvc.mak install

Once the unit test is built you just need to run it. They can be found
within the STLport bin folder.

=============
Using STLport
=============
Adjust your include and link paths in MSVC IDE (in 'Tools -> Options -> Directories'
for MSVC6 IDE). In the include files add the path to STLport's 'stlport' folder.
Make sure it is the first directory listed there. Add STLport's 'lib' folder for
the library files (order of paths doesn't matter here).

There are some preprocessor defines that control usage of the STLport in msvc
projects:

If you don't want to use the iostreams part of the library, you can specify the
define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the
library.

STLport uses automatic linking to find the proper .lib file. If you want to see
what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK.
When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you
have to specify the proper .lib file in the Project Settings, on the "link" tab.
The .lib names have the following syntax:

   stlport[d|stld][_x,_static,_statix].<STLport-Version>.lib

   d : debug build
   stld: debug build with _STLP_DEBUG (STL safe) mode
   _x: Build of STLport as a dll but statically link to the native runtime.
   _static : build of a static library
   _statix : build of a static library link dynamically to the native runtime.

Examples:

   stlport_static.5.0.lib - static release version, Version 5.0.0
   stlportd.5.0.lib - dll debug version, Version 5.0.0

When using STLport together with MFC, be sure to include the MFC headers first,
then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly
recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in
your project settings or in stlport/stl/config/user_config.h.

In order to enhance debugging with STLport you can optionally add the content of
the etc/autoexp.dat file in the autoexp.dat file coming with your Visual Studio
install.

Now you should be ready to use STLport.

============
Known issues
============

1. InterlockedIncrement

	If you experiment trouble with the InterlockedIncrement Win32 API function
like the following message:

C:\Program Files\Microsoft SDK\Include\.\winbase.h(1392) : error C2733: second C
linkage of overloaded function 'InterlockedIncrement' not allowed
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1390) : see declaration of
'InterlockedIncrement'

	It means that you are using the new Microsoft platform SDK. There is no
way to known it from STLport code so you have to signal it in the
stlport/stl/config/user_config.h file (uncomment _STLP_NEW_PLATFORM_SDK in this file).

2. Native C/C++ library headers location

	If you experiment trouble with location of ctime and other Standard headers
while building or using STLport you might be using the compiler coming with a
platform SDK. If so please uncomment _STLP_USING_PLATFORM_SDK_COMPILER in
stlport/stl/config/user_config.h. If it still do not find native headers you will
perhaps need to change native headers relative path used by STLport. In this case use
_STLP_NATIVE_INCLUDE_PATH and associated macro in stlport/stl/config/host.h.

4. C symbols in std namespace

The compiler of MSVC++ 6 has a bug when dealing with symbols existant in both
the global namespace and symbols imported by a using-directive or a
using-declaration - it will report an ambiguous call to an overloaded
function (error C2668). Example:

void function();
namespace ns {
   void function();
   // or:
   // using ::function;
}

using ns::function;
// or:
// using namespace ns;

void call() {
   function();
}

Since we anticipate that using-declarations or even using-directives are common
use, STLport by default doesn't import or wrap functions that exist in both the
global namespace and namespace std, in particular those are functions with C
origin like fopen() or abs(). Also, it defines additional overloads for
functions like abs() (overloaded for int, long, float, double, long double) in
the global namespace.

In order to make STLport include them in the std namespace, you can define the
_STLP_DO_IMPORT_CSTD_FUNCTIONS macro. Doing so, you will have to explicitely
scope all your functions calls like std::abs() though - otherwise you only get
the global abs(int) from the C library.

  Here is a description of how you can use STLport to read/write utf8 files.
utf8 is a way of encoding wide characters. As so, management of encoding in
the C++ Standard library is handle by the codecvt locale facet which is part
of the ctype category. However utf8 only describe how encoding must be
performed, it cannot be used to classify characters so it is not enough info
to know how to generate the whole ctype category facets of a locale
instance.

In C++ it means that the following code will throw an exception to
signal that creation failed:

#include <locale>
// Will throw a std::runtime_error exception.
std::locale loc(".utf8");

For the same reason building a locale with the ctype facets based on
UTF8 is also wrong:

// Will throw a std::runtime_error exception:
std::locale loc(locale::classic(), ".utf8", std::locale::ctype);

The only solution to get a locale instance that will handle utf8 encoding
is to specifically signal that the codecvt facet should be based on utf8
encoding:

// Will succeed if there is necessary platform support.
locale loc(locale::classic(), new codecvt_byname<wchar_t, char, mbstate_t>(".utf8"));

  Once you have obtain a locale instance you can inject it in a file stream to
read/write utf8 files:

std::fstream fstr("file.utf8");
fstr.imbue(loc);

You can also access the facet directly to perform utf8 encoding/decoding operations:

typedef std::codecvt<wchar_t, char, mbstate_t> codecvt_t;
const codecvt_t& encoding = use_facet<codecvt_t>(loc);

Notes:

1. The dot ('.') is mandatory in front of utf8. This is a POSIX convention, locale
names have the following format:
language[_country[.encoding]]

Ex: 'fr_FR'
    'french'
    'ru_RU.koi8r'

2. utf8 encoding is only supported for the moment under Windows. The less common
utf7 encoding is also supported.

Programming under MS Windows CE with STLport
=============================================

This is supposed to give an overview for programming on MS Windows CE, with and
partially without STLport, what tools are available and what common pitfalls
exist. Note that for every supported compiler there is another readme file which
explains the specifics of that compiler.



Available compilers:
---------------------

- Embedded Visual C++ 3 (eVC3): this IDE/compiler is for the CE3 target platforms.
The included compiler is MSC12, the same as for VC6, so many workarounds for its
'features' apply here, too. STLport works out of the box with this.

- Embedded Visual C++ 4 (eVC4): basically the same as eVC3, but it can compile for
CE4.x and 5. Note that currently (2007-03-06) I haven't tested this with CE5,
because you can use a better compiler using VC8/VS2005. This compiler can be
downloaded for free from the MS website, including a product activation key.
STLport works out of the box with this.

- Visual C++ 8 (VC8) aka Visual Studio 2005 (VS2005): with this version (and
partially already version 7) the embedded and desktop IDEs have been merged again,
so it supports compiling for MS Windows CE, versions 5 and later. Note that the
freely downloadable express edition does not(!) allow compiling for CE. This IDE
uses MSC14 as compiler. STLport works out of the box with CE5.

- Platform Builders (PB): this tool is used to create a CE image. You can select the
modules (e.g. Explorer, but also C++ RTTI) you include in the image. These IDEs use
several different compilers (MSC12-14). STLport hasn't been tested with this
IDE, AFAIK.

- There used to be an addon for VC6(?) that allowed compiling for CE. This plugin
has been superceeded by eVC3/4 and support for it has been removed from STLport in
version 5.

- Others: some vendors (e.g. Intel) provide compilers that are able to generate
CE executables. I'm not aware of an attempt to compile STLport with them.



Environment specialties:
-------------------------

- In order to develop for a platform, the first thing you need is a so-called SDK.
This package includes headers and libraries that (more or less) resemble the APIs
available on the device. The IDEs come with a basic selection of SDKs, but in
general you need to retrieve an according SDK from the vendor. If you are the
vendor, you can generate an SDK for a platform with Platform Builder.

- The provided API is typically a subset of the 'normal' win32 API. Often, some
features are simply not supported, like security descriptors when opening files.
Also, these APIs are only supported for wchar_t strings, e.g. only CreateFileW()
and not CreateFileA().

- CE doesn't have a current directory, hence no relative paths to that dir. You can
have relative parts in global paths though.

- CE doesn't have environment variables, thus STLport can't support e.g.
setenv/getenv. It also doesn't attempt to provide workarounds.

- Since many features are optional (see the description of Platform Builder), it
is possible that you don't have e.g. a console that std::cout could write to. The
same applies to exceptions (see e.g. the add-on lib for RTTI for eVC4). Other
features might go amiss, too. This makes it hard for STLport to adapt to, in
particular because this information is not available outside PB, a header might
declare a function that in fact is not present. Keep this in mind when you get
linker errors.

- The supplied C++ standard library is extremely cut down, e.g. iostreams and
locales are missing completely.

- The supplied standard C API is at best rudimentary. Functions like e.g. time() or
clock() are declared but not defined. STLport doesn't include any workarounds for
these missing functions at present.

- All compilers are cross-compilers, i.e. you run them on a win32 host and they
produce executable code for the target platform. The same applies to the debugger,
which is connected via serial, USB or ethernet. Alternatively, there are emulators
that run on the host machine and simulate the target platform.

- The entrypoint for executables is generally WinMain. Normally, you would have
switched to a normal main() using /SUBSYSTEM:CONSOLE on the linker commandline.
The linkers for at least CE4 and 5 don't understand this switch, they claim it
conflicts with CE targets. Instead, set the entrypoint directly to
mainACRTStartup.

- The name of a DLL loaded via an import library can't be longer than 32 chars. If
this is not the case, the application will behave as if the DLL was not present or
couldn't be loaded for whatever other reason. This limitation applies to at least
CE 4 and 5.

Note for Windows users:

  It is highly recommended to declare the Windows OS version you are
targetting when building the library as well as when using it. You can do so
thanks to the well known Microsoft macros WINVER, _WIN32_WINDOWS or
_WIN32_WINNT, see your platform SDK documentation for a description
of those macros and how to use them. To define it when building the
library, use the configure script --extra-cxxflag option. Here is the
configuration to build STLport using Visual Studio 2005 and targetting
Windows XP:

configure -c msvc8 --extra-cxxflag "/D_WIN32_WINNT=0x0501"

  If you do not declare it at build time STLport will adapt to the PSDK in
use, windows.h gives a default value to WINVER. However, when using the
library, windows.h is not necessarily included, at least not by STLport
internally, so none of the macros are defined which will result in an
inconsistency in the build process which most of time will generate undefined
behavior at runtime.

  Here is the main reason for following this advise, the Windows 95
compatibility issue:

  Because of a modification in the behavior of the Win32 API functions
InterlockedIncrement and InterlockedDecrement after Windows 95, STLport
libraries built for Windows 95 cannot be used to generate an application
built for Windows XP for instance. So, if you build STLport with a Windows
95 PSDK, STLport will be ready for Windows 95. If you then use it without
defining _WIN32_WINDOWS to signal Windows 95 compatibility, STLport will
consider that it can use latest Windows OS features like the new
InterlockedIncrement and InterlockedDecrement functions which change the
memory footprint of some internal STLport objects making it incompatible
with the libraries built for Windows 95.

  Normally, doing so wouldn't generate any compilation or link error, you
would only experiment undefined behavior at runtime. In order to make this
problem more obvious STLport forces a link time error in debug mode (_DEBUG
macro defined).

Unresolved symbol will be:
  - 'building_for_at_least_windows98_but_library_built_for_windows95'
  if you are trying to use STLport libraries built for Windows 98 or later
  to generate an application targetting the Windows 95 platform.
  - 'building_for_windows95_but_library_built_for_at_least_windows98'
  if you are trying to use STLport libraries built for Windows 95 to generate
  an appliation targetting the

  Windows XP platform for instance.

  Of course, targetting the latest Windows OS versions will give you the best
performance from STLport. This is why when none of the platform macros are
defined STLport consider that there is no minimum OS requirement and will
use the latest API functions. There is only one exception to this behavior,
the SwitchToThread function that is used only if you define _WIN32_WINNT to a
value higher or equal to 0X0400.