Home | History | Annotate | Download | only in doc
      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