1 2 ======================================== 3 STLport README for eMbedded Visual C++ 3 4 ======================================== 5 6 by: Michael Fink, vividos (a] users.sourceforge.net, last edited 2005-11-15 7 8 ============ 9 Introduction 10 ============ 11 This document describes how STLport can be compiled and used with Microsoft 12 eMbedded Visual C++ 3. 13 14 For any further comments or questsion visit STLport mailing lists 15 http://stlport.sourceforge.net/Maillists.shtml or forums 16 https://sourceforge.net/forum/?group_id=146814 17 18 19 ============= 20 Prerequisites 21 ============= 22 To 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 ================ 30 Building STLport 31 ================ 32 Note: 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 34 to the "Using STLport" section. 35 36 If you want to compile for the Pocket PC 2002 SDK (which in most cases you want) 37 be sure to set the PLATFORM environment variable to "Pocket PC 2002", e.g. with 38 this command: 39 40 set PLATFORM=Pocket PC 2002 41 42 Open a command line prompt and execute the batch file that sets up compiling 43 for 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 45 WCEARM.bat and WCEx86.bat. Check if the environment variables are set up 46 properly after that call. You can also adjust the batch files to have the 47 PLATFORM variable set automatically. 48 49 Go into STLport's 'build\lib' folder and type: 50 51 configure.bat -c evc3 52 53 The makefiles are configured with the given settings. Call configure.bat with 54 the --help option to see all options. The program automatically tells you which 55 command line to use. If you want to install the libraries, add the "install" 56 target as follows: 57 58 nmake /fmsvc.mak install 59 60 All libraries (debug, stldebug, release) are now built, static and shared 61 ones. Import libraries (.lib files) are put in the 'lib\evc3-arm' folder, DLLs 62 are put in the 'bin\evc3-arm' folder. If you use another target platform, the 63 name of the folder is changed accordingly, e.g. evc3-x86 for emulator files. 64 65 Once STLport is built you can decrease the size of the STLport folder by 66 removing intermediate build files. This is done with the following command: 67 68 nmake /fmsvc.mak clobber 69 70 Note: MIPS platform is also available for build, but it may not compile or work 71 properly. Use with caution! 72 73 =============== 74 Testing STLport 75 =============== 76 You can use the unit tests to verify STLport behaves correctly. Change into 77 STLports 'build\test\unit' folder and type: 78 79 nmake /fmsvc.mak install 80 81 If you want to build the unit tests for the emulator, you have to reconfigure 82 STLport with the configure.bat, as described above. 83 84 Once the unit tests are built, upload the binary (found in the 'bin\evc3-arm' 85 folder) to your device or emulator and start it (the test runs for about 30 86 seconds, depending on the speed of the device). The file 'stlp_test.txt' is 87 created in the root folder of the device, which contains the unit test 88 results. It should report no errors. 89 90 ============= 91 Using STLport 92 ============= 93 Adjust your include and link paths in eVC3 in 'Tools -> Options -> Directories' 94 and add the paths for all platforms and CPUs on which you want to use STLport. 95 In the include files add the path to STLport's 'stlport' folder. Make sure it 96 is 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 100 There are some preprocessor defines that control usage of the STLport in evc3 101 projects: 102 103 Define the symbol _STLP_USE_STATIC_LIB when you want to statically link against 104 STLport. The linker will remove unused classes and methods then, saving some 105 space in the executable. 106 107 If you don't want to use the iostreams part of the library, you can specify the 108 define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the 109 library. 110 111 STLport uses automatic linking to find the proper .lib file. If you want to see 112 what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK. 113 When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you 114 have to specify the proper .lib file in the Project Settings, on the "link" tab. 115 The .lib names have the following syntax: 116 117 stlport(d|stld)[_static].<STLport-Version>.lib 118 119 Examples: 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 124 Note that usage of the _STLP_DEBUG mode is currently not recommended for 125 eMbedded Visual C++ builds using the ARM compiler, due to a compiler bug. 126 127 When using STLport together with MFC, be sure to include the MFC headers first, 128 then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly 129 recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in 130 your project settings or in stlport/stl/config/user_config.h. 131 132 Now you should be ready to use STLport. 133 134 ============ 135 Known 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
