lib/3rdparty/stlport/doc/README.msvc

   1
   2 ==================================================
   3 STLport README for Microsoft Visual C++ compilers.
   4 ==================================================
   5
   6 by: Francois Dumont, dums@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.