sdk/lib/3rdparty/stlport/doc/README.evc4

   1
   2 ========================================
   3 STLport README for eMbedded Visual C++ 4
   4 ========================================
   5
   6 by: Zdenek Nemec, zero@mapfactor.com, last edited 2005-10-17
   7
   8 ============
   9 Introduction
  10 ============
  11 This document should provide step-by-step guidance for installing, testing and using the STLport library under Windows CE .NET 4.x
  12 (aka Windows Mobile 2003 aka Pocket PC 2003).
  13 For any further comments or questions visit the STLport mailing lists
  14 http://stlport.sourceforge.net/Maillists.shtml or forums
  15 https://sourceforge.net/forum/?group_id=146814
  16
  17 =============
  18 Prerequisites
  19 =============
  20 To build and use the STLport you will need following tools and libraries:
  21  - eMbedded Visual C++ 4.0 SP4
  22  - an SDK for your target platform with RTTI support
  23
  24 ================
  25 Building STLport
  26 ================
  27 First, make sure that RTTI is available. Not all SDKs that come with eVC4 also include
  28 the necessary libs, but there is a patch for the PPC2003 SDK, available at
  29 http://support.microsoft.com/default.aspx?scid=kb;[LN];830482.
  30
  31 Second, open command line and set proper system variables.
  32 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).
  33 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:
  34 WCEROOT=C:\Program Files\Microsoft eMbedded C++ 4.0
  35 SDKROOT=C:\Program Files\Windows CE Tools
  36
  37 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
  38 proper -c option (ie. "-c evc4"),
  39 then invoke following command: 'nmake /fmsvc.mak install' to build the library.
  40
  41 If anything goes wrong check if you met all prerequisities and if you set system vars accordingly to the makfile you are using.
  42 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.
  43
  44 You might want to repeat all those steps if you would like to have
  45 e.g. both ARM and x86 emulator binaries, just don't forget to do
  46 'nmake /fmsvc.mak clobber' before new build.
  47
  48 Note: MIPS platform is also available for build, but it may not compile or work properly. Use with caution!
  49
  50 ===============
  51 Testing STLport
  52 ===============
  53 When you successfuly build STLport libs, you should go to STLport/test/unit directory build and run the STLP test suite.
  54 Use 'nmake /fmsvc.mak' and keep in mind that you still have to have proper system variables set!
  55 Once test build has finished upload and run stlp_unit_test.exe to your emulator or device.
  56 Wait for a while (aprox. 2mins) until all tests are done.
  57 You should see two files next to your binary now.
  58 Check stlp_test.txt for any errors. If all tests passed you are ready to deploy STLport.
  59 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.
  60
  61 =============
  62 Using STLport
  63 =============
  64 Setting up the IDE:
  65 Before you start using STLport you have to set proper include and libraries search paths.
  66 Go to 'Tools'>'Options' menu in your eVC 4.0 and then to 'Directories' tab.
  67 For every platform you want to use STLport add STLport/stlport directory to the FIRST place in 'Include Files'
  68 and STLport/lib directory in 'Library files' section.
  69
  70 Setting up projects:
  71 When using STLport together with MFC, you have to define _STLP_USE_MFC to properly include and use STLport.
  72
  73 By default, exception support is not activated. You can detect this via _CPPUNWIND and activate this via /GX.
  74 Without exception support, e.g. std::bad_alloc is not available, causing compile errors for some code.
  75
  76 Also, there is only one runtime available but the IDE doesn't add the corresponding switch to the command line.
  77 The right switch (selecting a dynamically linked runtime) is IMHO /MD or /MDd. This then also switches STLport to dynamic linking.
  78 Alternatively, you can #define _DLL for your project, which achieves the same but, again IMHO, is a less clean solution.
  79
  80 ============
  81 Known issues
  82 ============
  83 - The compilers that come with eVC4 are almost bug-to-bug compatible with
  84 the one from VC6, so most workarounds for that compiler apply here, too.
  85
  86 - There is a bug in the MIPS compiler that comes with eVC4 which only surfaces
  87 under certain conditions:
  88  * in release mode with global optimizations on (#pragma optimize("g", on))
  89  * a baseclass has (at least) two pointer members
  90  * a derived class adds no data members
  91  * the derived class' cctor defers to the basclass' compiler-generated cctor
  92  * it is passed as template parameter to a function
  93 The smallest testcase I could come up with is this:
  94         struct base {
  95                 void* ptr1;
  96                 void* ptr2;
  97         };
  98         struct derived: public base {
  99                 derived() {}
 100                 derived(const derived& __x): base(__x) {}
 101         };
 102
 103         template<typename SomeType> void function( SomeType st1, SomeType st2) {}
 104
 105         struct test {
 106                 derived tmp;
 107                 ~test() { function(tmp, tmp); }
 108         };
 109         test test;
 110 ..which causes an internal compiler error. Removing the base::ptr1, adding data
 111 to derived, making function() a normal function, or turning off optimization
 112 (#pragma optimize("g", off)) all causes the code to compile. This bug affects
 113 iterators of deque and vector<bool>.
 114
 115 - Because of interdependancy between STLport and native Standard library headers
 116 STLport headers should always be included first in your translation unit (.cpp
 117 file). That is to say that:
 118
 119 //Wrong headers order:
 120 #include <windows.h>
 121 #include <cstdlib>
 122
 123 // Correct headers order
 124 #include <cstdlib>
 125 #include <windows.h>
 126