Home | History | Annotate | Download | only in doc
      1 
      2 ========================================
      3 STLport README for eMbedded Visual C++ 4
      4 ========================================
      5 
      6 by: Zdenek Nemec, zero (a] 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 
    127