1 2======================================== 3STLport README for eMbedded Visual C++ 4 4======================================== 5 6by: Zdenek Nemec, zero@mapfactor.com, last edited 2005-10-17 7 8============ 9Introduction 10============ 11This 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). 13For any further comments or questions visit the STLport mailing lists 14http://stlport.sourceforge.net/Maillists.shtml or forums 15https://sourceforge.net/forum/?group_id=146814 16 17============= 18Prerequisites 19============= 20To 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================ 25Building STLport 26================ 27First, make sure that RTTI is available. Not all SDKs that come with eVC4 also include 28the necessary libs, but there is a patch for the PPC2003 SDK, available at 29http://support.microsoft.com/default.aspx?scid=kb;[LN];830482. 30 31Second, open command line and set proper system variables. 32This 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). 33NOTE: 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: 34WCEROOT=C:\Program Files\Microsoft eMbedded C++ 4.0 35SDKROOT=C:\Program Files\Windows CE Tools 36 37Third, when you are 100percent sure you've set correctly systems variables go to the STLport/build/lib dir and run the configure.bat with 38proper -c option (ie. "-c evc4"), 39then invoke following command: 'nmake /fmsvc.mak install' to build the library. 40 41If anything goes wrong check if you met all prerequisities and if you set system vars accordingly to the makfile you are using. 42At 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 44You might want to repeat all those steps if you would like to have 45e.g. both ARM and x86 emulator binaries, just don't forget to do 46'nmake /fmsvc.mak clobber' before new build. 47 48Note: MIPS platform is also available for build, but it may not compile or work properly. Use with caution! 49 50=============== 51Testing STLport 52=============== 53When you successfuly build STLport libs, you should go to STLport/test/unit directory build and run the STLP test suite. 54Use 'nmake /fmsvc.mak' and keep in mind that you still have to have proper system variables set! 55Once test build has finished upload and run stlp_unit_test.exe to your emulator or device. 56Wait for a while (aprox. 2mins) until all tests are done. 57You should see two files next to your binary now. 58Check stlp_test.txt for any errors. If all tests passed you are ready to deploy STLport. 59If 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============= 62Using STLport 63============= 64Setting up the IDE: 65Before you start using STLport you have to set proper include and libraries search paths. 66Go to 'Tools'>'Options' menu in your eVC 4.0 and then to 'Directories' tab. 67For every platform you want to use STLport add STLport/stlport directory to the FIRST place in 'Include Files' 68and STLport/lib directory in 'Library files' section. 69 70Setting up projects: 71When using STLport together with MFC, you have to define _STLP_USE_MFC to properly include and use STLport. 72 73By default, exception support is not activated. You can detect this via _CPPUNWIND and activate this via /GX. 74Without exception support, e.g. std::bad_alloc is not available, causing compile errors for some code. 75 76Also, there is only one runtime available but the IDE doesn't add the corresponding switch to the command line. 77The right switch (selecting a dynamically linked runtime) is IMHO /MD or /MDd. This then also switches STLport to dynamic linking. 78Alternatively, you can #define _DLL for your project, which achieves the same but, again IMHO, is a less clean solution. 79 80============ 81Known issues 82============ 83- The compilers that come with eVC4 are almost bug-to-bug compatible with 84the 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 87under 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 93The 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 111to derived, making function() a normal function, or turning off optimization 112(#pragma optimize("g", off)) all causes the code to compile. This bug affects 113iterators of deque and vector<bool>. 114 115- Because of interdependancy between STLport and native Standard library headers 116STLport headers should always be included first in your translation unit (.cpp 117file). 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 127