doc/README.borland

==================================================
STLport README for Borland C++ compilers.
==================================================

by: Francois Dumont, dums@stlport.com, last edited 20 May 2006

============
Introduction
============
This document describes how STLport can be compiled and used with
Borland compilers.

For any further comments or questions 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:
 - Borland C++ compiler package 5.5.1 or higher version.

    In order to build STLport the Borland compiler and linker have to
  be correctly configurated too. That is to say:

    * For the Borland compiler bcc32:

    In Borland's 'bin' directory (same directory as bcc32.exe), create a 
  bcc32.cfg file containing the compiler option giving it the path to 
  native Borland headers:

	-I%BORLAND_PATH%\BCC55\include

    * For the resource compiler brcc32:

    Create an environment variable INCLUDE containing path to native Borland
    headers and especially the windows.h file

	set INCLUDE=%BORLAND_PATH%\BCC55\include

    * For the Borland linker ilink32:

    You need to give path to both the Borland libs and Borland PSDK libs.
    For that you have to create, in the same directory as ilink32.exe, a 
    configuration file, ilink32.cfg, that contains:

	-L%BORLAND_PATH%\BCC55\lib;%BORLAND_PATH%\BCC55\lib\PSDK

 - A GNU make tool. You can get one from www.mingw.org or www.cygwin.com.
   See README.mingw or README.cygwin for additional informations.

===================
Configuring STLport
===================
  This is intended to be an optional step, if you want to use default
configuration simply jump to next chapter 'Building STLport'. Open a console
and 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. For example,
to set the typical configuration for most Borland compilers, run 

    configure -c bcc

================
Building STLport
================
  This is a step by step description of the actions to take in order to build 
and install the STLport libraries:

1. Open a console, you can use a Msys, Cygwin or Windows console.

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

3. Run the following command:
	make -fbcc.mak install

	Where 'make' is the GNU make utility you have installed. The name of
GNU make utility may differ, such as 'mingw32-make'.  -f is a make option
telling it which makefile to use. You have of course to choose the 
appropriate makefile for your compiler, 'bcc.mak' in our case.

	Once the command returns you will have all the necessary import libraries 
in STLport's 'lib' folder and DLLs in STLport's 'bin' folder.  For a 
description of the generated libraries check the FAQ file in the 'doc' folder.  
For a quick start guide to the STLport make system, see the README file in the 
'build/lib' folder.

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

  make -fbcc.mak install

This will build and install the unit tests with STLport dynamic libraries.
Once the unit tests are built you just need to run them.  They can be found
in STLport's bin, bin-g or bin-stlg folders.  To rebuild the unit tests 
with STLport static libraries, type:

  make -fbcc.mak clean
  make -fbcc.mak install-static

=============
Using STLport
=============
Adjust your include and link paths in Borland IDE or in the command line config
files. 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).

Now you should be ready to use STLport.

============
Known limitations
============

1. If you extend a locale facet based on a Standard facet definition you will
have to grant your own facet id defition. Ex extracted from
test/unit/fstream_test.cpp:

#include <locale>

using namespace std;

struct my_state {
  char dummy;
};

struct my_traits : public char_traits<char> {
  typedef my_state state_type;
  typedef fpos<state_type> pos_type;
};

class my_codecvt : public codecvt<char, char, my_state>
{};

// Mandatory locale facet id definition:
template <>
locale::id codecvt<char, char, my_state>::id;

2. If you get a linker memory error, e.g. LME351, it probably means that full
source debugging is enabled and Borland's .TDS file has exceeded the memory 
capacity of Borland's linker (ilink32.exe).  To resolve this error, check
Borland's website for the latest patch for ilink32.exe.  In the alternative,
disable full source debugging in build\Makefiles\gmake\bcc.mak by deleting 
the -v option in the OPT settings.

3. For "'uname' is not recognized . . .", see "Configuring STLport" above.