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