Home | History | Annotate | only in /external/stlport/doc
Up to higher level directory
NameDateSize
build_system.txt31-Jul-20103.5K
FAQ31-Jul-201021.2K
pointer_specialization.txt31-Jul-20103.6K
README.borland31-Jul-20105K
README.cygwin31-Jul-20101.3K
README.dmc31-Jul-20102.5K
README.evc331-Jul-20106.2K
README.evc431-Jul-20105.6K
README.evc831-Jul-20103.9K
README.evc931-Jul-20103.7K
README.intel31-Jul-20101,022
README.mingw31-Jul-20101.9K
README.msvc31-Jul-20106.9K
README.utf831-Jul-20101.8K
README.wince31-Jul-20104.6K
README.windows31-Jul-20102.8K
stlport_namespaces.txt31-Jul-20104.2K

README.borland

      1 
      2 ==================================================
      3 STLport README for Borland C++ compilers.
      4 ==================================================
      5 
      6 by: Francois Dumont, dums (a] stlport.com, last edited 20 May 2006
      7 
      8 ============
      9 Introduction
     10 ============
     11 This document describes how STLport can be compiled and used with
     12 Borland compilers.
     13 
     14 For any further comments or questions visit STLport mailing lists
     15 http://stlport.sourceforge.net/Maillists.shtml or forums
     16 https://sourceforge.net/forum/?group_id=146814
     17 
     18 =============
     19 Prerequisites
     20 =============
     21 To build and use STLport you will need following tools and libraries:
     22  - Borland C++ compiler package 5.5.1 or higher version.
     23 
     24     In order to build STLport the Borland compiler and linker have to
     25   be correctly configurated too. That is to say:
     26 
     27     * For the Borland compiler bcc32:
     28 
     29     In Borland's 'bin' directory (same directory as bcc32.exe), create a 
     30   bcc32.cfg file containing the compiler option giving it the path to 
     31   native Borland headers:
     32 
     33 	-I%BORLAND_PATH%\BCC55\include
     34 
     35     * For the resource compiler brcc32:
     36 
     37     Create an environment variable INCLUDE containing path to native Borland
     38     headers and especially the windows.h file
     39 
     40 	set INCLUDE=%BORLAND_PATH%\BCC55\include
     41 
     42     * For the Borland linker ilink32:
     43 
     44     You need to give path to both the Borland libs and Borland PSDK libs.
     45     For that you have to create, in the same directory as ilink32.exe, a 
     46     configuration file, ilink32.cfg, that contains:
     47 
     48 	-L%BORLAND_PATH%\BCC55\lib;%BORLAND_PATH%\BCC55\lib\PSDK
     49 
     50  - A GNU make tool. You can get one from www.mingw.org or www.cygwin.com.
     51    See README.mingw or README.cygwin for additional informations.
     52 
     53 ===================
     54 Configuring STLport
     55 ===================
     56   This is intended to be an optional step, if you want to use default
     57 configuration simply jump to next chapter 'Building STLport'. Open a console
     58 and go to the STLport build/lib folder. Run
     59 
     60 	configure --help
     61 
     62   This command will present you the different available build options. Just follow
     63 the instructions to set STLport configuration according your needs. For example,
     64 to set the typical configuration for most Borland compilers, run 
     65 
     66     configure -c bcc
     67 
     68 ================
     69 Building STLport
     70 ================
     71   This is a step by step description of the actions to take in order to build 
     72 and install the STLport libraries:
     73 
     74 1. Open a console, you can use a Msys, Cygwin or Windows console.
     75 
     76 2. Go to the STLport build/lib folder:
     77 	cd C:\STLport\build\lib
     78 
     79 3. Run the following command:
     80 	make -fbcc.mak install
     81 
     82 	Where 'make' is the GNU make utility you have installed. The name of
     83 GNU make utility may differ, such as 'mingw32-make'.  -f is a make option
     84 telling it which makefile to use. You have of course to choose the 
     85 appropriate makefile for your compiler, 'bcc.mak' in our case.
     86 
     87 	Once the command returns you will have all the necessary import libraries 
     88 in STLport's 'lib' folder and DLLs in STLport's 'bin' folder.  For a 
     89 description of the generated libraries check the FAQ file in the 'doc' folder.  
     90 For a quick start guide to the STLport make system, see the README file in the 
     91 'build/lib' folder.
     92 
     93 ===============
     94 Testing STLport
     95 ===============
     96 You can use the unit tests to verify STLport behaves correctly. Change into
     97 STLport's 'build/test/unit' folder and type:
     98 
     99   make -fbcc.mak install
    100 
    101 This will build and install the unit tests with STLport dynamic libraries.
    102 Once the unit tests are built you just need to run them.  They can be found
    103 in STLport's bin, bin-g or bin-stlg folders.  To rebuild the unit tests 
    104 with STLport static libraries, type:
    105 
    106   make -fbcc.mak clean
    107   make -fbcc.mak install-static
    108 
    109 =============
    110 Using STLport
    111 =============
    112 Adjust your include and link paths in Borland IDE or in the command line config
    113 files. In the include files add the path to STLport's 'stlport' folder. Make sure
    114 it is the first directory listed there. Add STLport's 'lib' folder for the library
    115 files (order of paths doesn't matter here).
    116 
    117 Now you should be ready to use STLport.
    118 
    119 ============
    120 Known limitations
    121 ============
    122 
    123 1. If you extend a locale facet based on a Standard facet definition you will
    124 have to grant your own facet id defition. Ex extracted from
    125 test/unit/fstream_test.cpp:
    126 
    127 #include <locale>
    128 
    129 using namespace std;
    130 
    131 struct my_state {
    132   char dummy;
    133 };
    134 
    135 struct my_traits : public char_traits<char> {
    136   typedef my_state state_type;
    137   typedef fpos<state_type> pos_type;
    138 };
    139 
    140 class my_codecvt : public codecvt<char, char, my_state>
    141 {};
    142 
    143 // Mandatory locale facet id definition:
    144 template <>
    145 locale::id codecvt<char, char, my_state>::id;
    146 
    147 2. If you get a linker memory error, e.g. LME351, it probably means that full
    148 source debugging is enabled and Borland's .TDS file has exceeded the memory 
    149 capacity of Borland's linker (ilink32.exe).  To resolve this error, check
    150 Borland's website for the latest patch for ilink32.exe.  In the alternative,
    151 disable full source debugging in build\Makefiles\gmake\bcc.mak by deleting 
    152 the -v option in the OPT settings.
    153 
    154 3. For "'uname' is not recognized . . .", see "Configuring STLport" above. 
    155

README.cygwin

      1 The cygwin platform is used to build STLport with different compilers.
      2 
      3 - gcc (native compiler):
      4 
      5   Makefile : gcc.mak
      6 
      7   Notes:
      8 
      9     1. Static builds (archive)
     10 
     11     If you use the static version of the STLport libraries you have
     12   to define the _STLP_USE_STATIC_LIB macro in order to have your
     13   executable linked correctly.
     14 
     15     2. Link
     16 
     17     Under this platform STLport is complete replacement for libstdc++.
     18   It means that when you were linking with libstdc++ (-lstdc++) you only
     19   have to replace it with STLport (-lstlport.5.2 for instance). However
     20   default gcc behavior is to automatically link libstdc++ and a number of
     21   other system libs. To avoid this behavior you have to use the -nodefaultlibs
     22   compiler option and explicitely give all libraries by yourself. See build of
     23   unit tests to see what library you might need, here is the list when this
     24   note was written:
     25 
     26   without -mnocygwin option:
     27 
     28     -lstlportg.5.2 -lgcc -lm -lc -lpthread -lkernel32
     29 
     30   with -mno-cygwin option:
     31 
     32     -lstlportg.5.2 -lgcc -lmingw32 -lmingwex -lmsvcrt -lm -lmoldname
     33     -lcoldname -lkernel32
     34 
     35     3. No cygwin
     36 
     37     To build STLport libraries that do not depend on cygwin1.dll
     38   making them freely redistributable pass the following option to
     39   the configure script:
     40 
     41   ./configure --with-extra-cflags=-mno-cygwin --with-extra-cxxflags=-mno-cygwin
     42 
     43 - Borland C++ compiler
     44

README.dmc

      1 ==================================================
      2 STLport README for Digital Mars C++ compilers.
      3 ==================================================
      4 
      5 Build of STLport with Digital Mars C++ compiler is very similar
      6 to the one for Microsoft Visual Studio compiler (see README.msvc).
      7 
      8 Below are some additional hints. [DMC users are encouraged to 
      9 contribute additional information.] 
     10 
     11 =============
     12 Prerequisites
     13 =============
     14 
     15  - Digital Mars C++ 8.49 or above
     16 
     17  - A GNU environment with make tool. Prefer MinGW/MSys to Cygwin because the
     18    latter contains a link command that is also the name of the Digital Mars linker
     19    and you might experiment collision between both commands.
     20    See README.mingw for additional information.
     21 
     22 ===================
     23 Installing STLport
     24 ===================
     25 
     26  - STLport directory can be almost anywhere EXCEPT native dm\include directory.
     27 
     28 ===================
     29 Configuring STLport
     30 ===================
     31 
     32  - In a console window go to the STLport build\lib folder. Run
     33 
     34 	  configure -c dmc
     35 
     36 ================
     37 Building STLport
     38 ================
     39 
     40  - To build STLport libraries:
     41 
     42     cd [STLport dir]\build\lib
     43     [mingw32-make] -f dmc.mak install
     44 
     45  - To build STLport (dynamic) unit tests:
     46 
     47     cd [STLport dir]\build\test\unit
     48     [mingw32-make] -f dmc.mak install
     49 
     50 ============
     51 Known issues
     52 ============
     53 
     54 1. typeinfo.h
     55 
     56   DMC forces inclusion of typeinfo.h header at the begining of any
     57 translation unit. This breaks the STLport include schema, especially
     58 when building the library. As a workaround STLport typeinfo.h simply
     59 include native DMC header not performing any internal STLport work as
     60 importing things to STLport namespace. As a result typeinfo.h should
     61 never be reference in user code, as it is neither a C nor a C++ header
     62 this is not considered as a major limitation. The C++ Standard header
     63 is typeinfo.
     64 
     65 2. link.exe and lib.exe
     66 
     67   STLport makefiles for DMC use dm_link and dm_lib instead of link and lib to
     68 avoid conflicts with other vendors' linkers and archivers.  To build STLport 
     69 with DMC, please copy or rename the following files:
     70   
     71   copy dm\bin\link.exe dm\bin\dm_link.exe
     72   copy dm\bin\lib.exe dm\bin\dm_lib.exe
     73 
     74 3. Free online version. 
     75 
     76   If DMC's free online version reports compiler or linker errors, the 
     77 solution may be in a free online CD update.  Download and unzip all free 
     78 CD patches for versions 8.30 and above, in consecutive order, overwriting
     79 previous files. Then install free online version 8.49 or above, overwriting 
     80 previous files. 
     81 
     82

README.evc3

      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

README.evc4

      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

README.evc8

      1 setup VC8 for CE:
      2 ------------------
      3 
      4 - VC8 doesn't have any setup batchfiles that prepare the environment for compiling
      5 with CE. You can take those from eVC4 and adapt them or write your own. This snippet
      6 should get you going:
      7 
      8   rem you need to adapt at least these three
      9   set OSVERSION=WCE500
     10   set PLATFORM=MY_OWN_PLATFORM
     11   set TARGETCPU=MIPSII
     12 
     13   rem the compiler is always cl.exe, different compilers are in different paths
     14   set CC=cl.exe
     15   rem obviously, these need to be adjusted to where you installed VS2005 and the SDKs
     16   set VSINSTALLDIR=C:\Programme\Microsoft Visual Studio 8
     17   set SDKROOT=C:\Programme\Windows CE Tools
     18 
     19   set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_mips;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
     20   set PLATFORMROOT=%SDKROOT%\%OSVERSION%\%PLATFORM%
     21 
     22   rem add libs and includes from the SDK
     23   set INCLUDE=%PLATFORMROOT%\include\%TARGETCPU%;%PLATFORMROOT%\MFC\include;%PLATFORMROOT%\ATL\include
     24   set LIB=%PLATFORMROOT%\lib\%TARGETCPU%;%PLATFORMROOT%\MFC\lib\%TARGETCPU%;%PLATFORMROOT%\ATL\lib\%TARGETCPU%
     25 
     26   rem add libs that came with VC8
     27   rem Note: there are more libs and includes under ce\atlmfc, not sure if these are needed.
     28   set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%
     29   
     30   
     31 - The snippet below can be used to build STLport for Pocket PC 2003 (using the
     32   Pocket PC 2003 SDK shipped with Visual Studio 2005, this is the SDK used when
     33   compiling programs from within the IDE):
     34 
     35   set OSVERSION=WCE420
     36   set PLATFORM=POCKET PC 2003
     37   set TARGETCPU=ARMV4
     38 
     39   rem the compiler is always cl.exe, different compilers are in different paths
     40   set CC=cl.exe
     41 
     42   rem obviously, these need to be adjusted to where you installed VS2005
     43   set VSINSTALLDIR=C:\Program Files\Microsoft Visual Studio 8
     44   set SDKROOT=%VSINSTALLDIR%\SmartDevices\SDK
     45 
     46   set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_arm;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
     47   set PLATFORMROOT=%SDKROOT%\PocketPC2003
     48 
     49   rem add libs and includes from the SDK
     50   set INCLUDE=%PLATFORMROOT%\include
     51   set LIB=%PLATFORMROOT%\lib\%TARGETCPU%
     52 
     53   rem add libs that came with VC8
     54   set INCLUDE=%INCLUDE%;%VSINSTALLDIR%\VC\ce\atlmfc\include
     55   set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%;%VSINSTALLDIR%\VC\ce\atlmfc\lib\%TARGETCPU%
     56 
     57 
     58 You should now be able to run cl.exe for the target you expected.
     59 
     60 - The cross compilers of VC8 are the same version as for the native target, i.e. MSC14.
     61 
     62 - The cross compiler for MIPS has the same bug as mentioned in doc/README.evc4 and
     63 the same workaround applies. However, using 'whole program optimization', it results
     64 in an error in the link phase.
     65 
     66 - In order for STLport to recognize which target you are compiling for, you need to have
     67 some macros defined, e.g. for the target architecture. The compilers do that partially on
     68 their own, but not sufficiently. Therefore, STLport requires these defines:
     69 
     70  -- These are generally set for CE:
     71   _UNICODE;UNICODE;_WIN32;WIN32;UNDER_CE;WINCE;
     72  -- This one uses an environment variable to set the CE version:
     73   _WIN32_WCE=$(CEVER);
     74  -- These are used to help STLport recognise the target architecture:
     75   $(ARCHFAM);$(_ARCHFAM_);$(INSTRUCTIONSET)
     76  Note that the instructionset is not strictly needed for x86 but definitely for ARM. It
     77  doesn't hurt for x86 though, so I'd always set these in any new project.
     78  -- For release builds:
     79   NDEBUG;
     80  -- For debug builds:
     81   DEBUG;_DEBUG;
     82  -- For debug builds with additional STLport diagnostics:
     83   DEBUG;_DEBUG;_STLP_DEBUG;
     84  -- For MFC applications:
     85   _AFXDLL;
     86 
     87 - Further settings:
     88  Code generation: Multithreaded [Debug] DLL
     89  Language: enable RTTI
     90  Optimization: maximise speed and enable whole program optimization for release builds
     91 
     92 - Linker settings:
     93  Ignore specific libraries: libc.lib;libcd.lib
     94  Commandline: /SUBSYSTEM:WINDOWSCE
     95  Optimisation: /LTCG for release builds
     96 
     97 - Resource compiler:
     98  Define: UNDER_CE;WINCE;_WIN32_WCE=$(CEVER)
     99 
    100

README.evc9

      1 setup VC9 for CE:
      2 ------------------
      3 
      4 - VC9 doesn't have any setup batchfiles that prepare the environment for compiling
      5 with CE. You can take those from eVC4 and adapt them or write your own. This snippet
      6 should get you going:
      7 
      8   rem you need to adapt at least these three
      9   set OSVERSION=WCE500
     10   set PLATFORM=MY_OWN_PLATFORM
     11   set TARGETCPU=MIPSII
     12 
     13   rem the compiler is always cl.exe, different compilers are in different paths
     14   set CC=cl.exe
     15   rem obviously, these need to be adjusted to where you installed VS2008 and the SDKs
     16   set VSINSTALLDIR=C:\Programme\Microsoft Visual Studio 9.0
     17   set SDKROOT=C:\Programme\Windows CE Tools
     18 
     19   set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_mips;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
     20   set PLATFORMROOT=%SDKROOT%\%OSVERSION%\%PLATFORM%
     21 
     22   rem add libs and includes from the SDK
     23   set INCLUDE=%PLATFORMROOT%\include\%TARGETCPU%;%PLATFORMROOT%\MFC\include;%PLATFORMROOT%\ATL\include
     24   set LIB=%PLATFORMROOT%\lib\%TARGETCPU%;%PLATFORMROOT%\MFC\lib\%TARGETCPU%;%PLATFORMROOT%\ATL\lib\%TARGETCPU%
     25 
     26   rem add libs that came with VC9
     27   rem Note: there are more libs and includes under ce\atlmfc, you need to add these
     28   rem instead of the ones in the SDK if you want to use the newer version of ATL/MFC.
     29   set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%
     30 
     31 
     32 - The snippet below can be used to build STLport for Pocket PC 2003 (using the
     33   Pocket PC 2003 SDK shipped with Visual Studio 2008, this is the SDK used when
     34   compiling programs from within the IDE):
     35 
     36   set OSVERSION=WCE420
     37   set PLATFORM=POCKET PC 2003
     38   set TARGETCPU=ARMV4
     39 
     40   rem the compiler is always cl.exe, different compilers are in different paths
     41   set CC=cl.exe
     42 
     43   rem obviously, these need to be adjusted to where you installed VS2008
     44   set VSINSTALLDIR=C:\Program Files\Microsoft Visual Studio 9.0
     45   set SDKROOT=%VSINSTALLDIR%\SmartDevices\SDK
     46 
     47   set PATH=%VSINSTALLDIR%\VC\ce\bin\x86_arm;%VSINSTALLDIR%\VC\bin;%VSINSTALLDIR%\Common7\IDE;%PATH%
     48   set PLATFORMROOT=%SDKROOT%\PocketPC2003
     49 
     50   rem add libs and includes from the SDK
     51   set INCLUDE=%PLATFORMROOT%\include
     52   set LIB=%PLATFORMROOT%\lib\%TARGETCPU%
     53 
     54   rem add libs that came with VC9
     55   set INCLUDE=%INCLUDE%;%VSINSTALLDIR%\VC\ce\atlmfc\include
     56   set LIB=%LIB%;%VSINSTALLDIR%\VC\ce\lib\%TARGETCPU%;%VSINSTALLDIR%\VC\ce\atlmfc\lib\%TARGETCPU%
     57 
     58 
     59 You should now be able to run cl.exe for the target you expected.
     60 
     61 - The cross compilers of VC9 are the same version as for the native target, i.e. MSC15.
     62 
     63 - In order for STLport to recognize which target you are compiling for, you need to have
     64 some macros defined, e.g. for the target architecture. The compilers do that partially on
     65 their own, but not sufficiently. Therefore, STLport requires these defines:
     66 
     67  -- These are generally set for CE:
     68   _UNICODE;UNICODE;_WIN32;WIN32;UNDER_CE;WINCE;
     69  -- This one uses an environment variable to set the CE version:
     70   _WIN32_WCE=$(CEVER);
     71  -- These are used to help STLport recognise the target architecture:
     72   $(ARCHFAM);$(_ARCHFAM_);$(INSTRUCTIONSET)
     73  Note that the instructionset is not strictly needed for x86 but definitely for ARM. It
     74  doesn't hurt for x86 though, so I'd always set these in any new project.
     75  -- For release builds:
     76   NDEBUG;
     77  -- For debug builds:
     78   DEBUG;_DEBUG;
     79  -- For debug builds with additional STLport diagnostics:
     80   DEBUG;_DEBUG;_STLP_DEBUG;
     81  -- For MFC applications:
     82   _AFXDLL;
     83 
     84 - Further settings:
     85  Code generation: Multithreaded [Debug] DLL
     86  Language: enable RTTI
     87  Optimization: maximise speed and enable whole program optimization for release builds
     88 
     89 - Linker settings:
     90  Ignore specific libraries: libc.lib;libcd.lib
     91  Commandline: /SUBSYSTEM:WINDOWSCE
     92  Optimisation: /LTCG for release builds
     93 
     94 - Resource compiler:
     95  Define: UNDER_CE;WINCE;_WIN32_WCE=$(CEVER)
     96

README.intel

      1 Build of STLport with Intel C++ compiler for Windows is identical
      2 to the one for Microsoft Visual Studio compiler (see README.msvc).
      3 
      4 Known issues:
      5 
      6 1. If you have bind your Intel C++ compiler to the Visual Studio 6
      7 install and build your application without the -Qvc6 option you might
      8 experiement linking issue concerning 'std::unexpected' missing symbol.
      9 The reason of this problem is that without -Qvc6, ICL adds necessary
     10 code to invoke std::unexpected function when a raised exception is
     11 different to the one specified in a function prototype. As VC6 library
     12 do not contain this symbol ICL cannot find it anywhere.
     13 
     14   As a workaround, STLport has its own std::unexpected implementation
     15 that you will find in src/dll_main.cpp. ICL is looking for a static
     16 symbol so if you use STLport static lib ICL will use its std::unexpected
     17 implementation but if you use STLport dynamic lib then ICL won't find
     18 it. You only need then to copy/paste the STLport implementation somewhere
     19 in your implementation and ICL will be happy.
     20

README.mingw

      1   The MinGW GNU make command can be used to build STLport with different
      2 compilers
      3 
      4 - gcc (native compiler):
      5 
      6   Makefile : gcc.mak
      7 
      8   Notes:
      9 
     10     1. Static library (archive)
     11 
     12     If you use the static version of the STLport libraries
     13   you have to define the _STLP_USE_STATIC_LIB macro in order
     14   to have your executable linked correctly.
     15 
     16     2. Shell
     17 
     18     You will need MSys in order to build STLport.
     19 
     20     Be carefull about what make command you are using. STLport comes with a
     21   GNU make build system design for unix like platforms, make files have not
     22   been adapted for the Windows platform. So you have to use the make command
     23   coming with the MinGW package 'mingw32-make' and not the one coming with MSys
     24   that is a portage of the GNU make for Windows.
     25 
     26     3. Threading configuration
     27 
     28     STLport libraries are built per default in order to be used in a
     29   multithreaded environment. Under MinGW it means that we use the '-mthread'
     30   compiler option. Don't forget to add it to your compiler command line too
     31   if you want to use STLport libraries. You can also ask for not thread
     32   safe libraries using the --no-thread configure script option.
     33 
     34     4. Linking
     35 
     36     In this environment STLport is almost complete replacement for libstdc++.
     37   It means that when you were linking with libstdc++ (-lstdc++) you only have
     38   to replace it with STLport (-lstlport.5.2 for instance) and with libsupc++
     39   containing language compiler support (lsupc++). However default gcc
     40   behavior is to automatically link libstdc++ and a number of other system libs.
     41   To avoid this behavior you have to use the -nodefaultlibs compiler option and
     42   explicitely give all libraries by yourself. See build of unit tests to see what
     43   library you might need, here is the list when this note was written:
     44 
     45     -lstlportg.5.2 -lsupc++ -lgcc_s -lmingw32 -lmingwex -lmsvcrt -lm -lmoldname
     46     -lcoldname -lkernel32
     47 
     48 - Borland C++ compiler:
     49 
     50   Makefile : bcc.mak
     51 
     52 - Digital Mars C++ compiler:
     53 
     54   Makefile : dmc.mak
     55 
     56

README.msvc

      1 
      2 ==================================================
      3 STLport README for Microsoft Visual C++ compilers.
      4 ==================================================
      5 
      6 by: Francois Dumont, dums (a] stlport.com, last edited 08/02/2005
      7 
      8 ============
      9 Introduction
     10 ============
     11 This document describes how STLport can be compiled and used with Microsoft
     12 Visual C++ 6 SP5. It can also be used for the MSVC++ family.
     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 Prerequisites
     20 =============
     21 To build and use STLport you will need following tools and libraries:
     22  - Microsoft Visual C++ 6.0 with at least Service Pack 5 or any higher
     23  version.
     24 
     25 ===================
     26 Configuring STLport
     27 ===================
     28 In a console window go to the STLport build/lib folder. Run
     29 
     30 	configure --help
     31 
     32 This command will present you the different available build options. Just follow
     33 the instructions to set STLport configuration according your needs. The only
     34 mandatory configuration is to declare what is the compiler you are going to
     35 use, for MSVC 6 it is:
     36 
     37 	configure -c msvc6
     38 
     39 ================
     40 Building STLport
     41 ================
     42 This is a step by step description of the actions to take in order to have
     43 the STLport library built:
     44 
     45 1. Open a console window. You can get it executing cmd or command depending
     46 on your Windows OS.
     47 
     48 2. Go to MSVC++ Bin directory with a default MSVC6 install it is
     49 	cd "C:\Program Files\Microsoft Visual Studio\VC98\Bin"
     50 
     51 3. Run the vcvars32.bat script. This sets the environment variables required
     52 to have the MSVC++ compiler run during the build process. The most important
     53 one is the PATH variable so that you can call the cl.exe command which is the
     54 MSVC++ command line compiler. [You may omit this step, if you chose 'Install paths
     55 to access command-line tools' during Microsoft Visual Studio installation procedure.]
     56 
     57 4. Go to the STLport build/lib folder:
     58 	cd C:\STLport\build\lib
     59 
     60 5. Run the following command:
     61 	nmake /fmsvc.mak install
     62 
     63 	nmake is the make utility from Microsoft. /f is an nmake option
     64 telling it which make file script to use. You have of course to grant the 
     65 closer make file to your effective compiler, msvc.mak in our case.
     66 
     67 	Once the command returns, you will have all the necessary libraries within
     68 the STLport lib folder. For a description of the generated libraries check the README
     69 file within the src folder.
     70 
     71 ===============
     72 Testing STLport
     73 ===============
     74 You can use the unit tests to verify STLport behaves correctly. Change into
     75 STLports 'build/test/unit' folder and type:
     76 
     77   nmake /fmsvc.mak install
     78 
     79 Once the unit test is built you just need to run it. They can be found
     80 within the STLport bin folder.
     81 
     82 =============
     83 Using STLport
     84 =============
     85 Adjust your include and link paths in MSVC IDE (in 'Tools -> Options -> Directories'
     86 for MSVC6 IDE). In the include files add the path to STLport's 'stlport' folder. 
     87 Make sure it is the first directory listed there. Add STLport's 'lib' folder for
     88 the library files (order of paths doesn't matter here).
     89 
     90 There are some preprocessor defines that control usage of the STLport in msvc
     91 projects:
     92 
     93 If you don't want to use the iostreams part of the library, you can specify the
     94 define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the
     95 library.
     96 
     97 STLport uses automatic linking to find the proper .lib file. If you want to see
     98 what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK.
     99 When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you
    100 have to specify the proper .lib file in the Project Settings, on the "link" tab.
    101 The .lib names have the following syntax:
    102 
    103    stlport[d|stld][_x,_static,_statix].<STLport-Version>.lib
    104 
    105    d : debug build
    106    stld: debug build with _STLP_DEBUG (STL safe) mode
    107    _x: Build of STLport as a dll but statically link to the native runtime.
    108    _static : build of a static library
    109    _statix : build of a static library link dynamically to the native runtime.
    110    
    111 Examples:
    112 
    113    stlport_static.5.0.lib - static release version, Version 5.0.0
    114    stlportd.5.0.lib - dll debug version, Version 5.0.0
    115 
    116 When using STLport together with MFC, be sure to include the MFC headers first,
    117 then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly
    118 recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in
    119 your project settings or in stlport/stl/config/user_config.h.
    120 
    121 In order to enhance debugging with STLport you can optionally add the content of
    122 the etc/autoexp.dat file in the autoexp.dat file coming with your Visual Studio
    123 install.
    124 
    125 Now you should be ready to use STLport.
    126 
    127 ============
    128 Known issues
    129 ============
    130 
    131 1. InterlockedIncrement
    132 
    133 	If you experiment trouble with the InterlockedIncrement Win32 API function
    134 like the following message:
    135 
    136 C:\Program Files\Microsoft SDK\Include\.\winbase.h(1392) : error C2733: second C
    137 linkage of overloaded function 'InterlockedIncrement' not allowed
    138 C:\Program Files\Microsoft SDK\Include\.\winbase.h(1390) : see declaration of
    139 'InterlockedIncrement'
    140 
    141 	It means that you are using the new Microsoft platform SDK. There is no
    142 way to known it from STLport code so you have to signal it in the 
    143 stlport/stl/config/user_config.h file (uncomment _STLP_NEW_PLATFORM_SDK in this file).
    144 
    145 2. Native C/C++ library headers location
    146 
    147 	If you experiment trouble with location of ctime and other Standard headers
    148 while building or using STLport you might be using the compiler coming with a
    149 platform SDK. If so please uncomment _STLP_USING_PLATFORM_SDK_COMPILER in
    150 stlport/stl/config/user_config.h. If it still do not find native headers you will
    151 perhaps need to change native headers relative path used by STLport. In this case use
    152 _STLP_NATIVE_INCLUDE_PATH and associated macro in stlport/stl/config/host.h.
    153 
    154 4. C symbols in std namespace
    155 
    156 The compiler of MSVC++ 6 has a bug when dealing with symbols existant in both
    157 the global namespace and symbols imported by a using-directive or a 
    158 using-declaration - it will report an ambiguous call to an overloaded
    159 function (error C2668). Example:
    160 
    161 void function();
    162 namespace ns {
    163    void function();
    164    // or:
    165    // using ::function;
    166 }
    167 
    168 using ns::function;
    169 // or:
    170 // using namespace ns;
    171 
    172 void call() {
    173    function();
    174 }
    175 
    176 Since we anticipate that using-declarations or even using-directives are common
    177 use, STLport by default doesn't import or wrap functions that exist in both the
    178 global namespace and namespace std, in particular those are functions with C 
    179 origin like fopen() or abs(). Also, it defines additional overloads for
    180 functions like abs() (overloaded for int, long, float, double, long double) in
    181 the global namespace.
    182 
    183 In order to make STLport include them in the std namespace, you can define the
    184 _STLP_DO_IMPORT_CSTD_FUNCTIONS macro. Doing so, you will have to explicitely 
    185 scope all your functions calls like std::abs() though - otherwise you only get
    186 the global abs(int) from the C library.
    187

README.utf8

      1   Here is a description of how you can use STLport to read/write utf8 files.
      2 utf8 is a way of encoding wide characters. As so, management of encoding in
      3 the C++ Standard library is handle by the codecvt locale facet which is part
      4 of the ctype category. However utf8 only describe how encoding must be
      5 performed, it cannot be used to classify characters so it is not enough info
      6 to know how to generate the whole ctype category facets of a locale
      7 instance.
      8 
      9 In C++ it means that the following code will throw an exception to
     10 signal that creation failed:
     11 
     12 #include <locale>
     13 // Will throw a std::runtime_error exception.
     14 std::locale loc(".utf8");
     15 
     16 For the same reason building a locale with the ctype facets based on
     17 UTF8 is also wrong:
     18 
     19 // Will throw a std::runtime_error exception:
     20 std::locale loc(locale::classic(), ".utf8", std::locale::ctype);
     21 
     22 The only solution to get a locale instance that will handle utf8 encoding
     23 is to specifically signal that the codecvt facet should be based on utf8
     24 encoding:
     25 
     26 // Will succeed if there is necessary platform support.
     27 locale loc(locale::classic(), new codecvt_byname<wchar_t, char, mbstate_t>(".utf8"));
     28 
     29   Once you have obtain a locale instance you can inject it in a file stream to
     30 read/write utf8 files:
     31 
     32 std::fstream fstr("file.utf8");
     33 fstr.imbue(loc);
     34 
     35 You can also access the facet directly to perform utf8 encoding/decoding operations:
     36 
     37 typedef std::codecvt<wchar_t, char, mbstate_t> codecvt_t;
     38 const codecvt_t& encoding = use_facet<codecvt_t>(loc);
     39 
     40 Notes:
     41 
     42 1. The dot ('.') is mandatory in front of utf8. This is a POSIX convention, locale
     43 names have the following format:
     44 language[_country[.encoding]]
     45 
     46 Ex: 'fr_FR'
     47     'french'
     48     'ru_RU.koi8r'
     49 
     50 2. utf8 encoding is only supported for the moment under Windows. The less common
     51 utf7 encoding is also supported.
     52

README.wince

      1 Programming under MS Windows CE with STLport
      2 =============================================
      3 
      4 This is supposed to give an overview for programming on MS Windows CE, with and
      5 partially without STLport, what tools are available and what common pitfalls
      6 exist. Note that for every supported compiler there is another readme file which
      7 explains the specifics of that compiler.
      8 
      9 
     10 
     11 Available compilers:
     12 ---------------------
     13 
     14 - Embedded Visual C++ 3 (eVC3): this IDE/compiler is for the CE3 target platforms.
     15 The included compiler is MSC12, the same as for VC6, so many workarounds for its
     16 'features' apply here, too. STLport works out of the box with this.
     17 
     18 - Embedded Visual C++ 4 (eVC4): basically the same as eVC3, but it can compile for
     19 CE4.x and 5. Note that currently (2007-03-06) I haven't tested this with CE5,
     20 because you can use a better compiler using VC8/VS2005. This compiler can be
     21 downloaded for free from the MS website, including a product activation key.
     22 STLport works out of the box with this.
     23 
     24 - Visual C++ 8 (VC8) aka Visual Studio 2005 (VS2005): with this version (and
     25 partially already version 7) the embedded and desktop IDEs have been merged again,
     26 so it supports compiling for MS Windows CE, versions 5 and later. Note that the
     27 freely downloadable express edition does not(!) allow compiling for CE. This IDE
     28 uses MSC14 as compiler. STLport works out of the box with CE5.
     29 
     30 - Platform Builders (PB): this tool is used to create a CE image. You can select the
     31 modules (e.g. Explorer, but also C++ RTTI) you include in the image. These IDEs use
     32 several different compilers (MSC12-14). STLport hasn't been tested with this
     33 IDE, AFAIK.
     34 
     35 - There used to be an addon for VC6(?) that allowed compiling for CE. This plugin
     36 has been superceeded by eVC3/4 and support for it has been removed from STLport in
     37 version 5.
     38 
     39 - Others: some vendors (e.g. Intel) provide compilers that are able to generate
     40 CE executables. I'm not aware of an attempt to compile STLport with them.
     41 
     42 
     43 
     44 Environment specialties:
     45 -------------------------
     46 
     47 - In order to develop for a platform, the first thing you need is a so-called SDK.
     48 This package includes headers and libraries that (more or less) resemble the APIs
     49 available on the device. The IDEs come with a basic selection of SDKs, but in
     50 general you need to retrieve an according SDK from the vendor. If you are the
     51 vendor, you can generate an SDK for a platform with Platform Builder.
     52 
     53 - The provided API is typically a subset of the 'normal' win32 API. Often, some
     54 features are simply not supported, like security descriptors when opening files.
     55 Also, these APIs are only supported for wchar_t strings, e.g. only CreateFileW()
     56 and not CreateFileA().
     57 
     58 - CE doesn't have a current directory, hence no relative paths to that dir. You can 
     59 have relative parts in global paths though.
     60 
     61 - CE doesn't have environment variables, thus STLport can't support e.g.
     62 setenv/getenv. It also doesn't attempt to provide workarounds.
     63 
     64 - Since many features are optional (see the description of Platform Builder), it
     65 is possible that you don't have e.g. a console that std::cout could write to. The
     66 same applies to exceptions (see e.g. the add-on lib for RTTI for eVC4). Other
     67 features might go amiss, too. This makes it hard for STLport to adapt to, in
     68 particular because this information is not available outside PB, a header might
     69 declare a function that in fact is not present. Keep this in mind when you get
     70 linker errors.
     71 
     72 - The supplied C++ standard library is extremely cut down, e.g. iostreams and
     73 locales are missing completely.
     74 
     75 - The supplied standard C API is at best rudimentary. Functions like e.g. time() or
     76 clock() are declared but not defined. STLport doesn't include any workarounds for
     77 these missing functions at present.
     78 
     79 - All compilers are cross-compilers, i.e. you run them on a win32 host and they
     80 produce executable code for the target platform. The same applies to the debugger,
     81 which is connected via serial, USB or ethernet. Alternatively, there are emulators
     82 that run on the host machine and simulate the target platform.
     83 
     84 - The entrypoint for executables is generally WinMain. Normally, you would have
     85 switched to a normal main() using /SUBSYSTEM:CONSOLE on the linker commandline.
     86 The linkers for at least CE4 and 5 don't understand this switch, they claim it
     87 conflicts with CE targets. Instead, set the entrypoint directly to 
     88 mainACRTStartup.
     89 
     90 - The name of a DLL loaded via an import library can't be longer than 32 chars. If
     91 this is not the case, the application will behave as if the DLL was not present or
     92 couldn't be loaded for whatever other reason. This limitation applies to at least
     93 CE 4 and 5.
     94 
     95

README.windows

      1 Note for Windows users:
      2 
      3   It is highly recommended to declare the Windows OS version you are
      4 targetting when building the library as well as when using it. You can do so
      5 thanks to the well known Microsoft macros WINVER, _WIN32_WINDOWS or
      6 _WIN32_WINNT, see your platform SDK documentation for a description
      7 of those macros and how to use them. To define it when building the
      8 library, use the configure script --extra-cxxflag option. Here is the
      9 configuration to build STLport using Visual Studio 2005 and targetting
     10 Windows XP:
     11 
     12 configure -c msvc8 --extra-cxxflag "/D_WIN32_WINNT=0x0501"
     13 
     14   If you do not declare it at build time STLport will adapt to the PSDK in
     15 use, windows.h gives a default value to WINVER. However, when using the
     16 library, windows.h is not necessarily included, at least not by STLport
     17 internally, so none of the macros are defined which will result in an
     18 inconsistency in the build process which most of time will generate undefined
     19 behavior at runtime.
     20 
     21   Here is the main reason for following this advise, the Windows 95
     22 compatibility issue:
     23 
     24   Because of a modification in the behavior of the Win32 API functions
     25 InterlockedIncrement and InterlockedDecrement after Windows 95, STLport
     26 libraries built for Windows 95 cannot be used to generate an application
     27 built for Windows XP for instance. So, if you build STLport with a Windows
     28 95 PSDK, STLport will be ready for Windows 95. If you then use it without
     29 defining _WIN32_WINDOWS to signal Windows 95 compatibility, STLport will
     30 consider that it can use latest Windows OS features like the new
     31 InterlockedIncrement and InterlockedDecrement functions which change the
     32 memory footprint of some internal STLport objects making it incompatible
     33 with the libraries built for Windows 95.
     34 
     35   Normally, doing so wouldn't generate any compilation or link error, you
     36 would only experiment undefined behavior at runtime. In order to make this
     37 problem more obvious STLport forces a link time error in debug mode (_DEBUG
     38 macro defined).
     39 
     40 Unresolved symbol will be:
     41   - 'building_for_at_least_windows98_but_library_built_for_windows95'
     42   if you are trying to use STLport libraries built for Windows 98 or later
     43   to generate an application targetting the Windows 95 platform.
     44   - 'building_for_windows95_but_library_built_for_at_least_windows98'
     45   if you are trying to use STLport libraries built for Windows 95 to generate
     46   an appliation targetting the
     47   
     48   Windows XP platform for instance.
     49 
     50   Of course, targetting the latest Windows OS versions will give you the best
     51 performance from STLport. This is why when none of the platform macros are
     52 defined STLport consider that there is no minimum OS requirement and will
     53 use the latest API functions. There is only one exception to this behavior,
     54 the SwitchToThread function that is used only if you define _WIN32_WINNT to a
     55 value higher or equal to 0X0400.
     56