doc/README.msvc - platform/external/stlport - Git at Google


 ==================================================
 STLport README for Microsoft Visual C++ compilers.
 ==================================================

 by: Francois Dumont, dums@stlport.com, last edited 08/02/2005

 ============
 Introduction
 ============
 This document describes how STLport can be compiled and used with Microsoft
 Visual C++ 6 SP5. It can also be used for the MSVC++ family.

 For any further comments or questsion visit STLport mailing lists
 http://stlport.sourceforge.net/Maillists.shtml or forums
 https://sourceforge.net/forum/?group_id=146814

 =============
 Prerequisites
 =============
 To build and use STLport you will need following tools and libraries:
  - Microsoft Visual C++ 6.0 with at least Service Pack 5 or any higher
  version.

 ===================
 Configuring STLport
 ===================
 In a console window go to the STLport build/lib folder. Run

 	configure --help

 This command will present you the different available build options. Just follow
 the instructions to set STLport configuration according your needs. The only
 mandatory configuration is to declare what is the compiler you are going to
 use, for MSVC 6 it is:

 	configure -c msvc6

 ================
 Building STLport
 ================
 This is a step by step description of the actions to take in order to have
 the STLport library built:

 1. Open a console window. You can get it executing cmd or command depending
 on your Windows OS.

 2. Go to MSVC++ Bin directory with a default MSVC6 install it is
 	cd "C:\Program Files\Microsoft Visual Studio\VC98\Bin"

 3. Run the vcvars32.bat script. This sets the environment variables required
 to have the MSVC++ compiler run during the build process. The most important
 one is the PATH variable so that you can call the cl.exe command which is the
 MSVC++ command line compiler. [You may omit this step, if you chose 'Install paths
 to access command-line tools' during Microsoft Visual Studio installation procedure.]

 4. Go to the STLport build/lib folder:
 	cd C:\STLport\build\lib

 5. Run the following command:
 	nmake /fmsvc.mak install

 	nmake is the make utility from Microsoft. /f is an nmake option
 telling it which make file script to use. You have of course to grant the
 closer make file to your effective compiler, msvc.mak in our case.

 	Once the command returns, you will have all the necessary libraries within
 the STLport lib folder. For a description of the generated libraries check the README
 file within the src folder.

 ===============
 Testing STLport
 ===============
 You can use the unit tests to verify STLport behaves correctly. Change into
 STLports 'build/test/unit' folder and type:

   nmake /fmsvc.mak install

 Once the unit test is built you just need to run it. They can be found
 within the STLport bin folder.

 =============
 Using STLport
 =============
 Adjust your include and link paths in MSVC IDE (in 'Tools -> Options -> Directories'
 for MSVC6 IDE). In the include files add the path to STLport's 'stlport' folder.
 Make sure it is the first directory listed there. Add STLport's 'lib' folder for
 the library files (order of paths doesn't matter here).

 There are some preprocessor defines that control usage of the STLport in msvc
 projects:

 If you don't want to use the iostreams part of the library, you can specify the
 define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the
 library.

 STLport uses automatic linking to find the proper .lib file. If you want to see
 what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK.
 When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you
 have to specify the proper .lib file in the Project Settings, on the "link" tab.
 The .lib names have the following syntax:

    stlport[d|stld][_x,_static,_statix].<STLport-Version>.lib

    d : debug build
    stld: debug build with _STLP_DEBUG (STL safe) mode
    _x: Build of STLport as a dll but statically link to the native runtime.
    _static : build of a static library
    _statix : build of a static library link dynamically to the native runtime.

 Examples:

    stlport_static.5.0.lib - static release version, Version 5.0.0
    stlportd.5.0.lib - dll debug version, Version 5.0.0

 When using STLport together with MFC, be sure to include the MFC headers first,
 then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly
 recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in
 your project settings or in stlport/stl/config/user_config.h.

 In order to enhance debugging with STLport you can optionally add the content of
 the etc/autoexp.dat file in the autoexp.dat file coming with your Visual Studio
 install.

 Now you should be ready to use STLport.

 ============
 Known issues
 ============

 1. InterlockedIncrement

 	If you experiment trouble with the InterlockedIncrement Win32 API function
 like the following message:

 C:\Program Files\Microsoft SDK\Include\.\winbase.h(1392) : error C2733: second C
 linkage of overloaded function 'InterlockedIncrement' not allowed
 C:\Program Files\Microsoft SDK\Include\.\winbase.h(1390) : see declaration of
 'InterlockedIncrement'

 	It means that you are using the new Microsoft platform SDK. There is no
 way to known it from STLport code so you have to signal it in the
 stlport/stl/config/user_config.h file (uncomment _STLP_NEW_PLATFORM_SDK in this file).

 2. Native C/C++ library headers location

 	If you experiment trouble with location of ctime and other Standard headers
 while building or using STLport you might be using the compiler coming with a
 platform SDK. If so please uncomment _STLP_USING_PLATFORM_SDK_COMPILER in
 stlport/stl/config/user_config.h. If it still do not find native headers you will
 perhaps need to change native headers relative path used by STLport. In this case use
 _STLP_NATIVE_INCLUDE_PATH and associated macro in stlport/stl/config/host.h.

 4. C symbols in std namespace

 The compiler of MSVC++ 6 has a bug when dealing with symbols existant in both
 the global namespace and symbols imported by a using-directive or a
 using-declaration - it will report an ambiguous call to an overloaded
 function (error C2668). Example:

 void function();
 namespace ns {
    void function();
    // or:
    // using ::function;
 }

 using ns::function;
 // or:
 // using namespace ns;

 void call() {
    function();
 }

 Since we anticipate that using-declarations or even using-directives are common
 use, STLport by default doesn't import or wrap functions that exist in both the
 global namespace and namespace std, in particular those are functions with C
 origin like fopen() or abs(). Also, it defines additional overloads for
 functions like abs() (overloaded for int, long, float, double, long double) in
 the global namespace.

 In order to make STLport include them in the std namespace, you can define the
 _STLP_DO_IMPORT_CSTD_FUNCTIONS macro. Doing so, you will have to explicitely
 scope all your functions calls like std::abs() though - otherwise you only get
 the global abs(int) from the C library.

	==================================================
	STLport README for Microsoft Visual C++ compilers.
	==================================================

	by: Francois Dumont, dums@stlport.com, last edited 08/02/2005

	============
	Introduction
	============
	This document describes how STLport can be compiled and used with Microsoft
	Visual C++ 6 SP5. It can also be used for the MSVC++ family.

	For any further comments or questsion visit STLport mailing lists
	http://stlport.sourceforge.net/Maillists.shtml or forums
	https://sourceforge.net/forum/?group_id=146814

	=============
	Prerequisites
	=============
	To build and use STLport you will need following tools and libraries:
	- Microsoft Visual C++ 6.0 with at least Service Pack 5 or any higher
	version.

	===================
	Configuring STLport
	===================
	In a console window go to the STLport build/lib folder. Run

	configure --help

	This command will present you the different available build options. Just follow
	the instructions to set STLport configuration according your needs. The only
	mandatory configuration is to declare what is the compiler you are going to
	use, for MSVC 6 it is:

	configure -c msvc6

	================
	Building STLport
	================
	This is a step by step description of the actions to take in order to have
	the STLport library built:

	1. Open a console window. You can get it executing cmd or command depending
	on your Windows OS.

	2. Go to MSVC++ Bin directory with a default MSVC6 install it is
	cd "C:\Program Files\Microsoft Visual Studio\VC98\Bin"

	3. Run the vcvars32.bat script. This sets the environment variables required
	to have the MSVC++ compiler run during the build process. The most important
	one is the PATH variable so that you can call the cl.exe command which is the
	MSVC++ command line compiler. [You may omit this step, if you chose 'Install paths
	to access command-line tools' during Microsoft Visual Studio installation procedure.]

	4. Go to the STLport build/lib folder:
	cd C:\STLport\build\lib

	5. Run the following command:
	nmake /fmsvc.mak install

	nmake is the make utility from Microsoft. /f is an nmake option
	telling it which make file script to use. You have of course to grant the
	closer make file to your effective compiler, msvc.mak in our case.

	Once the command returns, you will have all the necessary libraries within
	the STLport lib folder. For a description of the generated libraries check the README
	file within the src folder.

	===============
	Testing STLport
	===============
	You can use the unit tests to verify STLport behaves correctly. Change into
	STLports 'build/test/unit' folder and type:

	nmake /fmsvc.mak install

	Once the unit test is built you just need to run it. They can be found
	within the STLport bin folder.

	=============
	Using STLport
	=============
	Adjust your include and link paths in MSVC IDE (in 'Tools -> Options -> Directories'
	for MSVC6 IDE). In the include files add the path to STLport's 'stlport' folder.
	Make sure it is the first directory listed there. Add STLport's 'lib' folder for
	the library files (order of paths doesn't matter here).

	There are some preprocessor defines that control usage of the STLport in msvc
	projects:

	If you don't want to use the iostreams part of the library, you can specify the
	define _STLP_NO_IOSTREAMS. In this mode there is no need to link against the
	library.

	STLport uses automatic linking to find the proper .lib file. If you want to see
	what import library STLport is going to use, define _STLP_VERBOSE_AUTO_LINK.
	When not using automatic linking (by specifying _STLP_DONT_USE_AUTO_LINK), you
	have to specify the proper .lib file in the Project Settings, on the "link" tab.
	The .lib names have the following syntax:

	stlport[d\|stld][_x,_static,_statix].<STLport-Version>.lib

	d : debug build
	stld: debug build with _STLP_DEBUG (STL safe) mode
	_x: Build of STLport as a dll but statically link to the native runtime.
	_static : build of a static library
	_statix : build of a static library link dynamically to the native runtime.

	Examples:

	stlport_static.5.0.lib - static release version, Version 5.0.0
	stlportd.5.0.lib - dll debug version, Version 5.0.0

	When using STLport together with MFC, be sure to include the MFC headers first,
	then include STLport headers, e.g. in your Stdafx.h. This way STLport correctly
	recognizes MFC usage. You also can define the macro _STLP_USE_MFC, either in
	your project settings or in stlport/stl/config/user_config.h.

	In order to enhance debugging with STLport you can optionally add the content of
	the etc/autoexp.dat file in the autoexp.dat file coming with your Visual Studio
	install.

	Now you should be ready to use STLport.

	============
	Known issues
	============

	1. InterlockedIncrement

	If you experiment trouble with the InterlockedIncrement Win32 API function
	like the following message:

	C:\Program Files\Microsoft SDK\Include\.\winbase.h(1392) : error C2733: second C
	linkage of overloaded function 'InterlockedIncrement' not allowed
	C:\Program Files\Microsoft SDK\Include\.\winbase.h(1390) : see declaration of
	'InterlockedIncrement'

	It means that you are using the new Microsoft platform SDK. There is no
	way to known it from STLport code so you have to signal it in the
	stlport/stl/config/user_config.h file (uncomment _STLP_NEW_PLATFORM_SDK in this file).

	2. Native C/C++ library headers location

	If you experiment trouble with location of ctime and other Standard headers
	while building or using STLport you might be using the compiler coming with a
	platform SDK. If so please uncomment _STLP_USING_PLATFORM_SDK_COMPILER in
	stlport/stl/config/user_config.h. If it still do not find native headers you will
	perhaps need to change native headers relative path used by STLport. In this case use
	_STLP_NATIVE_INCLUDE_PATH and associated macro in stlport/stl/config/host.h.

	4. C symbols in std namespace

	The compiler of MSVC++ 6 has a bug when dealing with symbols existant in both
	the global namespace and symbols imported by a using-directive or a
	using-declaration - it will report an ambiguous call to an overloaded
	function (error C2668). Example:

	void function();
	namespace ns {
	void function();
	// or:
	// using ::function;
	}

	using ns::function;
	// or:
	// using namespace ns;

	void call() {
	function();
	}

	Since we anticipate that using-declarations or even using-directives are common
	use, STLport by default doesn't import or wrap functions that exist in both the
	global namespace and namespace std, in particular those are functions with C
	origin like fopen() or abs(). Also, it defines additional overloads for
	functions like abs() (overloaded for int, long, float, double, long double) in
	the global namespace.

	In order to make STLport include them in the std namespace, you can define the
	_STLP_DO_IMPORT_CSTD_FUNCTIONS macro. Doing so, you will have to explicitely
	scope all your functions calls like std::abs() though - otherwise you only get
	the global abs(int) from the C library.