1 2======================================== 3STLport README for eMbedded Visual C++ 3 4======================================== 5 6by: Michael Fink, vividos@users.sourceforge.net, last edited 2005-11-15 7 8============ 9Introduction 10============ 11This document describes how STLport can be compiled and used with Microsoft 12eMbedded Visual C++ 3. 13 14For any further comments or questsion visit STLport mailing lists 15http://stlport.sourceforge.net/Maillists.shtml or forums 16https://sourceforge.net/forum/?group_id=146814 17 18 19============= 20Prerequisites 21============= 22To build and use STLport you will need following tools and libraries: 23 - eMbedded Visual C++ 3.0 24 - latest CVS version of STLport, use info from page 25 'http://stlport.sourceforge.net/CVS.shtml' to get it. 26 Note that you may have to get a different branch, please check out the 27 STLport forum "Announcements" which sourcecode is being worked on. 28 29================ 30Building STLport 31================ 32Note: if you don't plan to use the iostreams part of STLport (via the define 33_STLP_NO_IOSTREAMS), you don't have to build the library. You can skip straight 34to the "Using STLport" section. 35 36If you want to compile for the Pocket PC 2002 SDK (which in most cases you want) 37be sure to set the PLATFORM environment variable to "Pocket PC 2002", e.g. with 38this command: 39 40 set PLATFORM=Pocket PC 2002 41 42Open a command line prompt and execute the batch file that sets up compiling 43for ARM or x86 processors. These files usually are in a folder like 44'C:\Program Files\Windows CE eMbedded Tools\EVC\WCE300\BIN\' and are called 45WCEARM.bat and WCEx86.bat. Check if the environment variables are set up 46properly after that call. You can also adjust the batch files to have the 47PLATFORM variable set automatically. 48 49Go into STLport's 'build\lib' folder and type: 50 51 configure.bat -c evc3 52 53The makefiles are configured with the given settings. Call configure.bat with 54the --help option to see all options. The program automatically tells you which 55command line to use. If you want to install the libraries, add the "install" 56target as follows: 57 58 nmake /fmsvc.mak install 59 60All libraries (debug, stldebug, release) are now built, static and shared 61ones. Import libraries (.lib files) are put in the 'lib\evc3-arm' folder, DLLs 62are put in the 'bin\evc3-arm' folder. If you use another target platform, the 63name of the folder is changed accordingly, e.g. evc3-x86 for emulator files. 64 65Once STLport is built you can decrease the size of the STLport folder by 66removing intermediate build files. This is done with the following command: 67 68 nmake /fmsvc.mak clobber 69 70Note: MIPS platform is also available for build, but it may not compile or work 71 properly. Use with caution! 72 73=============== 74Testing STLport 75=============== 76You can use the unit tests to verify STLport behaves correctly. Change into 77STLports 'build\test\unit' folder and type: 78 79 nmake /fmsvc.mak install 80 81If you want to build the unit tests for the emulator, you have to reconfigure 82STLport with the configure.bat, as described above. 83 84Once the unit tests are built, upload the binary (found in the 'bin\evc3-arm' 85folder) to your device or emulator and start it (the test runs for about 30 86seconds, depending on the speed of the device). The file 'stlp_test.txt' is 87created in the root folder of the device, which contains the unit test 88results. It should report no errors. 89 90============= 91Using STLport 92============= 93Adjust your include and link paths in eVC3 in 'Tools -> Options -> Directories' 94and add the paths for all platforms and CPUs on which you want to use STLport. 95In the include files add the path to STLport's 'stlport' folder. Make sure it 96is the first directory listed there. Add STLport's 'lib\evc3-arm' or 97'lib\evc3-x86' (depending on what target you use) folder for the library files 98(order of paths doesn't matter here). 99 100There are some preprocessor defines that control usage of the STLport in evc3 101projects: 102 103Define the symbol _STLP_USE_STATIC_LIB when you want to statically link against 104STLport. The linker will remove unused classes and methods then, saving some 105space in the executable. 106 107If you don't want to use the iostreams part of the library, you can specify the 108define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the 109library. 110 111STLport uses automatic linking to find the proper .lib file. If you want to see 112what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK. 113When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you 114have to specify the proper .lib file in the Project Settings, on the "link" tab. 115The .lib names have the following syntax: 116 117 stlport(d|stld)[_static].<STLport-Version>.lib 118 119Examples: 120 121 stlport_static.5.0.lib - static release version, Version 5.0.0 122 stlportd_50.lib - dll debug version, Version 5.0.0 123 124Note that usage of the _STLP_DEBUG mode is currently not recommended for 125eMbedded Visual C++ builds using the ARM compiler, due to a compiler bug. 126 127When using STLport together with MFC, be sure to include the MFC headers first, 128then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly 129recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in 130your project settings or in stlport/stl/config/user_config.h. 131 132Now you should be ready to use STLport. 133 134============ 135Known issues 136============ 137 - Unit Tests in _STLP_DEBUG mode (target 'stldbg-shared') fails in 138 __stl_debug_engine::_M_detach() for several tests due to unknown reasons. 139 A compiler bug in the ARM compiler is suspected. 140 There is currently no workaround for this bug. It is recommended to not use 141 _STLP_DEBUG mode. 142 143 - Resource compiler issue: 144 145 The resource compiler is not a C++ compiler, it is a compiler that translates 146 resource files, i.e. files that describe dialogs, strings, version information 147 and other parts of the GUI on MS Windows systems. 148 149 The problem is that it includes files from the C/C++ include path, and 150 STLport uses mechanisms the resource compiler can't handle, e.g. using macro 151 names longer than 31 characters. 152 153 The workaround is to guard all affected headers (stdio.h, string.h, stdarg.h, 154 stdlib.h, ctype.h) against this. The resource compiler is detected by the 155 macro RC_INVOKED. 156 157 - See also README.evc4 issues. 158