BORLAND C++ RUNTIME LIBRARY SOURCE CODE 3.0 DOCUMENTATION _________________________________________________________ Please read this document carefully.

It contains information on how to install the Borland C++ Runtime Library source files, an overview of what the Runtime Library contains, instructions for modifying Runtime Library files, and Borland's licensing agreement. TABLE OF CONTENTS _________________ 1. 2. 3. 4. 5. Installing Library Sources Runtime Library Overview Modifying Library Files License Agreement More information on the batch files

1. INSTALLING LIBRARY SOURCES _____________________________ The following diagram shows the recommended directory structure for the libraries on a hard dis . This is also the directory structure created by the hard dis installation program, INSTALL. All of the batch files that build the RTL files assume this directory structure. In the diagram, and in the text that follows, we assume that you have installed the RTL directory structure in a subdirectory named \CRTL. If you have put the RTL directory structure in a subdirectory other than \CRTL, simply substitute the path to that directory wherever \CRTL appears. RECOMMENDED LIBRARY DIRECTORY STRUCTURE _______________________________________ \CRTL \CRTL\LOG \CRTL\LIB \CRTL\RTLINC \CRTL\CLIB \CRTL\IOSTREAM \CRTL\MATH \CRTL\EMU \CRTL\WINLIB \CRTL\WINLIB\NOTIMP library root directory; all batch files are contained here (BATCH.ZIP) compiler and assembler error message logs library files are created here library header files (RTLINC.ZIP) general library sources (CLIB1.ZIP, CLIB2.ZIP). C++ stream I/O library sources (IOSTREAM.ZIP) math library sources (MATH.ZIP) floating point initialization. (FPINIT.ASM in MATH.ZIP) Windows library sources (WINLIB.ZIP) Stubs for library functions not implemented under Windows.

To install the library source files on your hard dis , insert the library source distribution dis 1 in your floppy drive, and enter the following command at the DOS prompt:

A:INSTALL The INSTALL program will default to the library directories as shown above and extract the source and header/include files, placing them in the appropriate directories. It will also extract several batch files that may be used to recompile and/or rebuild the C and MATH libraries. It is a good idea to have a loo at these batch files, to see how the source modules are compiled and how the libraries are built. The following batch files will be placed in \CRTL: BUILD.BAT ALL.BAT Compiles and assembles ALL modules in one or more libraries, for one or more memory models. Compiles and assembles ALL modules in ALL libraries, for ALL memory models.

These batch files assume the recommended directory structure. For usage information and an example, see section 5 or enter the name of the batch file without any parameters. If you choose to compile or assemble a module without using the batch files, be aware that certain files need special switches. Ma e sure to chec the configuration files (TASM.CFG and TURBOC.CFG) and the batch files to find the necessary switches. 2. RUNTIME LIBRARY OVERVIEW ___________________________ Most of the library routines require .H files from Borland C++, and you'll also need TLIB, the object file librarian. The runtime libraries are bloc s of object code grouped together in several library files. These library files contain the general library routines and the standard math routines. FPINIT.ASM is provided to allow you to modify the floating-point initialization and termination process. If you used the installation batch file, this file will be found in a subdirectory called EMU. FPINIT.ASM is used to create two OBJ files, one for the emulator (FPINIT.OBJ) and one for inline 8087 instructions (FP87INIT.OBJ). The following command lines will create these two files from the EMU subdirectory. TASM /MX /t /z fpinit TASM /MX /t /z /DFP87 fpinit, fp87init Most of the modules contained in the runtime libraries are object files produced by compiling the library source files with the Borland C++ compiler. Some of the files contain inline assembly language code; therefore you will need a TASM 2.0 (or compatible) Macro Assembler to compile those source files. Finally, a few modules are written entirely in assembly language. Here is a ey to some of the file extensions found in the RTL: .C .CPP

C source file C++ source file

.H .CAS .ASM .ASI .CFG .ZIP

C header file C source file with inline assembler Assembler source file Include file needed for .ASM files Configuration files for Borland C++ and Turbo Assembler. Archive file

The library source files have been grouped together into several "archive" files (.ZIP extensions). An archive file contains a collection of files in a compressed form. You use the UNZIP utility to extract files from the archive. Here is the usage information for UNZIP: Usage: UNZIP [options] zipfile [destpath] [files...] Options: /o = overwrite existing files /c = extract file(s) to the console /t = test archive integrity zipfile destpath files /v = verbose listing of archive(s) /p = extract file(s) to the printer

Archive file name, wildcards *,? o . Default extension is .ZIP Destination for extracted files. Name(s) of files to extract. Wildcards *,? o . Default is ALL files. - Unpac all files in CLIB1 to current drive and directory. - Unpac all files in MATH.ZIP to C:\LIBRARY\MATH directory. - Unpac all .CPP and .CAS files in CLIB2.ZIP to drive C.

3. MODIFYING LIBRARY FILES __________________________ This section describes how to modify a source module, compile or assemble it, and replace it in a library. If you have installed the source using INSTALL, there are several batch files included to ma e your job easier; see section 5 for more information. You can modify a library file by first changing the corresponding source file, compiling (or assembling) the modified source file into an object file, and finally rebuilding the library files from its constituent object files. In order to compile most of the library source files, the standard header files and the library header files (contained in RTLINC.ZIP) #included in most of the C source files must be present on your system. They must be made available to Borland C++ through the -I option. The following steps are recommended for modifying a library module. You might want to modify all the modules you need, then rebuild the library (or libraries) from scratch. 1. Install all the source files on a hard dis using the installation procedure described in section 1. Even

UNZIP CLIB2 C: *.CPP *.CAS

UNZIP MATH C:\CRTL\MATH

Examples: UNZIP CLIB1

though you will not be modifying all of the source files, the ma efiles that build the libraries assume that all source files are present. 2. Figure out which module you need to modify, and to which library file(s) it belongs. The library listing feature of TLIB will be helpful here, since it shows all the modules in a library file, together with all the functions that the modules define. Use "tlib lib-name,con" or "tlib lib-name,listfile-name." Note that the general routine libraries (CS.LIB, CC.LIB, CM.LIB, CL.LIB, and CH.LIB) all contain the same set of modules, compiled for different memory models; li ewise for the math routine libraries (MATHS.LIB, MATHC.LIB, MATHM.LIB, MATHL.LIB, and MATHH.LIB), and the Windows libraries (CWS.LIB, CWC.LIB, CWM.LIB, CWL.LIB, and CWH.LIB). 3. Apply and test all the changes you need to ma e. To test a C library module, write a simple testing program, and compile and lin both modules at the same time; for example: BCC [options] tsrchp searchp.cas That way you ma e sure the tested module will not be lin ed in from the library. For an assembler file, assemble the library file, then lin it with a test file using BCC; for example:

TASM lrsh /MX; BCC [options] tstshf lrsh.obj 4. Recompile the module and replace it in the library file(s). The batch file BUILD.BAT is provided on the distribution dis to help with rebuilding the libraries. It compiles or assembles all modules that are more recent than the corresponding object files, or which do not have object files, then rebuilds the library from its object files. For batch file usage information and examples, see section 5 or enter the name of the batch file without any parameters. If you are using a floppy-based system, don't use these batch files. At this point, it's easier just to update the library with the .OBJ file. Remember, TLIB creates a bac up of the library file, so ma e sure you have plenty of space. 4. LICENSE AGREEMENT ____________________

Borland C++ Runtime Library Source Code Borland's No-Nonsense License Agreement Borland International, Inc. (Borland) is offering you a license to the source code to the Borland C++ Runtime Library portion of Borland C++ (the Source Programs), including updates that may later be supplied by Borland at additional cost, but not including the source code of the 8087 emulator or the graphics library. The Source Programs are protected by both United States copyright law and international treaty provisions. Therefore, you must treat the Source Programs just li e a boo , with the following single exception: Borland authorizes you to ma e archival copies of the Source Programs for the sole purpose of bac ing-up your programs and protecting your investments from loss. By "just li e a boo ," Borland means, for example, that the Source Programs may be used by any number of people and may be freely moved from one computer wor station to another, so long as there is no possibility of them being used at one computer wor station at the same time they are being used at another. Just as a boo can't be read by two different people in two different places at the same time, neither can the Source Programs be used by two different people in two different places at the same time. (Unless, of course, Borland's copyright has been violated.) You may modify the Source Programs, but the modified source code, regardless of the extent of the modifications, shall always remain Borland's source code. You may not remove or modify Borland's copyright and other proprietary copyright notices, and you may not transport any of the Source Programs to another computer operating system or environment. You are responsible for all claims, liability, and damages arising from your own modifications and the products which include them. You may use the Source Programs to support your licensed copies of Borland C++. This means you may include all or some of the original or modified Source Programs routines in your own Borland C++ based programs, but you may only distribute binary copies of such routines when lin ed into your executable programs. You may not distribute any source code for the original or modified Borland C++ Runtime Library under any circumstances. You are not, of course, restricted from distributing your own source code. All rights not specifically granted in this license are reserved by Borland. 5. MORE INFORMATION ON THE BATCH FILES ______________________________________ The following descriptions are of the batch files you may find useful when modifying the library source files. All of them assume that you have installed the sources by using INSTALL. Usage information can also be found by entering the name of the batch file without any parameters. There are two batch files that you can use to build libraries: ALL.BAT and BUILD.BAT. The batch files wor by invo ing MAKE with

a master MAKEFILE, \CRTL\MAKEFILE. This ma efile, in turn, invo es MAKE with ma efiles for specific libraries. These library-specific ma efiles have the extension .MAK. For example, one of the the ma efiles that is used to build the Windows libraries is \CRTL\WINLIB\WINLIB.MAK. Note that the ma efiles invo e TLIB with the /0 option when replacing modules in the CLIB and WINLIB libraries, and with the /0 /E options when replacing modules in the MATH libraries. If you want to build one or more library files to include debugging information (so that you can step through library calls with TC or TD), you have to remove both the /E and /0 options from the TLIB command line(s), as these options effectively remove all debugging information from library files. ENVIRONMENT VARIABLES _____________________ The batch files use two environment variables to determine which memory models should be used, and where the error log should be saved. The environment variable MODEL specifies which memory models should be used. Set it to all the memory model letters you want to use. Separate the letters with spaces, and be sure to use only lower-case letters. For example, if you want to compile for all memory models, use all the model letters: set MODEL=s c m l h If you want to compile for just one memory model, set MODEL to a single letter: use the command: set MODEL=s If you don't set MODEL, the batch files will use all memory models. The environment variable LOGFILE determines where the compiler and assembler error messages will be saved. If you want the error messages to be displayed on the screen, use the following command before you run the batch files: set LOGFILE=CON If you don't set LOGFILE, the batch files will set it to the default value ..\LOG\CRTL.LOG. The directory ..\LOG is a subdirectory of \CRTL, and if doesn't already exist, you must create it with the command: MKDIR \CRTL\LOG The batch files also use environment variables to control the operation of the compiler, assembler, and librarian. These variables are set in VARS.BAT. You can edit this file to change the operation of the tools. For example, if you want to compile with debugging information turned on, add -v to the line in VARS.BAT that defines the TC environment variable, and remove /0 from the line that defines the TLIB environment variable.

You should always run VARS.BAT before running BUILD.BAT. BUILD.BAT _________ This batch file will recompile all modified modules (or modules which have no corresponding object files) for a specific library (or all libraries) for one or more memory models. It places the resultant object files in the appropriate subdirectory (for example, the S subdirectory for small model). It then rebuilds the library from its object files. The "libtype" parameter specified which library should be built: CLIB, WINLIB, WINDLL, STARTUP, or MATH. If you want to build all libraries, specify ALL. The environment variable MODEL specifies which memory models are to be used. If MODEL is not set, BUILD.BAT uses all memory models. The current directory must be \CRTL when you run BUILD.BAT. Usage: build libtype Examples: build all build math build clib Note that recompiling all the source files using this batch file may ta e a considerable amount of time. But once the files have been compiled, subsequent runs of BUILD.BAT will compile only those modules that have changed. ALL.BAT _______ This batch file builds all libraries in all memory model by repeatedly invo ing BUILD.BAT. Not only will this will ta e a considerable amount of time, but will also consume large amounts of dis space.