Borland 2.0 C++ compiler User's Guide

PDF

Dokument

Reklama

BORLAND

2.0

Bar/ana

C++

Version 2.0

BORLAND INTERNATIONAL INC. 1800 GREEN HILLS ROAD

P.O. BOX 660001, SCOTTS VALLEY, CA 95067-0001

Rl

Borland products are trademarks or registered trademarks of

Borland International. Inc. Other brand and product names are trademarks or registered trademarks of their respective holders.

Windows, as used in this manual, refers to Microsoft's implementation of a windows system.

PRINTED IN THE USA.

10987654

c o

N T

E N

T s

Introduction

Typefaces used in this book ............ 2

Chapter 1 The Programmers Platform

Starting up and exiting ................ 4

Running in real mode ...............

Running in protected mode .......... 4

Windows and protected mode ...... 5

Command-line options ..............

The

option .................... 5

The

d option ....................

The

and

x options ............. 7

The

option ....................

The

option . . . . . . . . . . . . . . . . . . . .. 7

The

1m

option. . . . . . . . . . . . . . . . . . ..

p option .................... 7

The

r option. . . . . . . . . . . . . . . . . . . ..

Exiting Borland C++ ................ 8

The components ......................

The menu bar and menus ............ 8

Shortcuts ....................... 10

Borland C++ windows . . . . . . . . . . . . .. 13

Window management ............ 15

The status line .....................

Dialog boxes ......................

Check boxes and radio buttons .... 18

Input boxes and lists ............. 18

Editing ........................... 19

Project and configuration files ....... 20

Turbo C files .................... 20

Borland C++ project files . . . . . . . . .. 20

Configuration files ................. 21

Loading project files .............. 21

The project directory ............. 22

Desktop files .................... 22

Changing project files ............ 22

Default files ........ . . . . . . . . . . . .. 22

Chapter 2 Menus and options reference

:: (System) menu . . . . . . . . . . . . . . . . . . . .. 26

About ............................ 27

Clear Desktop ..................... 27

Repaint Desktop ...... . . . . . . . . . . . .. 27

Transfer items ........ . . . . . . . . . . . .. 27

File menu . . . . . . . . . . . . . . . . . . . . . . . . . .. 27

Open ............................. 28

Using the File list box. . . . . . . . . . . . . .. 29

New ............................. 29

Save ............................. 29

Save As ........................... 30

Save All .......................... 30

Change Dir ....................... 30

Print ............................. 31

Get Info .......................... 31

DOS Shell. .. .. .. .. .. .. .. . . .. .. . ...

Quit .............................. 33

Edit menu .......................... 33

Undo ............................. 34

Redo ............................. 35

Cut .............................. 35

Copy ............................. 35

Paste ............................. 35

Copy Example. . . . . . . . . . . . . . . . . . . .. 36

Show Clipboard ................... 36

Clear ............................. 36

Search menu ........................ 36

Find .............................. 37

Replace ........................... 38

Search Again . . . . . . . . . . . . . . . . . . . . .. 39

Go to Line Number ................ 39

Previous Error . . . . . . . . . . . . . . . . . . . .. 40

Next Error ........................

Locate Function . . . . . . . . . . . . . . . . . . ..

Runmenu .......................... 41

Run .............................. 41

Source code the same . . . . . . . . . . . .. 41

Source code modified . . . . . . . . . . . .. 41

Program Reset ......... ; . . . . . . . . . .. 42

Go to Cursor ...................... 42

Trace Into . . . . . . . . . . . . . . . . . . . . . . . .. 42

Step Over . . . . . . . . . . . . . . . . . . . . . . . .. 43

Arguments . . . . . . . . . . . . . . . . . . . . . . .. 44

Compile menu. . . . . . . . . . . . . . . . . . . . . .. 45

Compile to OBI .................... 45

Make EXE File . . . . . . . . . . . . . . . . . . . .. 45

Link EXE File . .. .. .. .. .... .. . .. . . .. 46

Build All . . . . . . . . . . . . . . . . . . . . . . . . .. 46

Remove Messages .....

. . . . . . . . . . .. 46

Debug menu ........................ 46

Inspect ........................... 47

Ordinal Inspector windows ....... 48

Pointer Inspector windows . . . . . . .. 48

Array Inspector windows ......... 49

Structure and union Inspector windows ....................... 49

Function Inspector windows ...... 49

Class Inspector windows . . . . . . . . .. 50

Constant Inspector window ....... 50

Type Inspector window . . . . . . . . . .. 50

Evaluate/Modify .................. 50

Call Stack . . . . . . . . . . . . . . . . . . . . . . . .. 51

Watches .......................... 54

Add Watch. . . . . . . . . . . . . . . . . . . . .. 54

Delete Watch .................... 54

Edit Watch . . . . . . . . . . . . . . . . . . . . .. 54

Remove All Watches ............. 55

Toggle Breakpoint ................. 55

Breakpoints ....................... 55

Project menu ........................ 57

Open Project ...................... 57

Close Project ...................... 58

Add Item ......................... 58

Delete Item. . . . . . . . . . . . . . . . . . . . . . .. 58

Local Options ..................... 59

Include Files ...................... 60

Options menu .................. . . . .. 60

Compiler ......................... 61

Code Generation. . . . . . . . . . . . . . . .. 61

Entry /Exit Code . . . . . . . . . . . . . . . .. 65

C++ Options .................... 67

Optimizations ................... 68

Source .......................... 69

Messages ....................... 70

Names ......................... 73

Transfer .......................... 74

Transfer macros ................. 76

Running DOS commands ......... 82

Transfer memory settings ......... 82

Make ............................. 82

Linker ............................ 84

The Set Application Options dialog box .............................. 86

Debugger . . . . . . . . . . . . . . . . . . . . . . . .. 87

Directories ........................ 89

Environment ...................... 90

Preferences. . . . . . . . . . . . . . . . . . . . .. 90

Editor .......................... 92

Mouse .......................... 94

Desktop ........................ 94

Save ............................. 95

Window menu ...................... 95

Size/Move . . . . . . . . . . .. . . . . . . . . . . .. 95

Zoom ............................ 96

Tile .............................. 96

Cascade .......................... 96

Next ............................. 96

Close ............................. 96

Message .......................... 96

Output ........................... 97

Watch ............................ 97

User Screen ....................... 97

Project ............................ 98

Project Notes ...................... 98

List .............................. 98

Help menu ... ". . . . . . . . . . . . . . . . . . . . . .. 98

Contents . . . . . . . . . . . . . . . . . . . . . . . .. 100

Index ......................... " ... 100

Topic Search ....................... 100 ii

Previous Topic ..................... 100

Help on Help . . . . . . . . . . . . . . . . . . . . . .. 101

Chapter 3 Building a Windows application

103

The basic process ................... 103

Compiling and linking within the IDE . 104

Understanding resource files ....... 105

Understanding module definition files ............................. 105

Compiling and linking WHELLO ... 105

Setting compile and link options .. 106

Compiling and linking from the command line ............................... 107

Compiling from the command line .. 107

Linking from the command line . . . .. 108

Using a makefile .................. 109

Another makefile for Windows ... 110

Prologs and epilogs ................. 111

The _export keyword .............. 113

Prologs, epilogs, and exports: a summary ........................ 113

Memory models .................... 115

Linking for Windows . . . . . . . . . . . . . . .. 115

Linking in the IDE ................ 116

Linking with TLINK . . . . . . . . . . . . . .. 116

Linker options .................. 116

Linking .OB] and .LIB files ....... 117

Linking .OBJ and .LIB files for

DLLs .......................... 118

Building a project for a Windows program ........................... 118

WinMain .......................... 120

The Resource Compiler .............. 120

Resource Compiler syntax. . . . . . . . .. 121

Dynamic link libraries ............... 123

Compiling and linking a DLL within the

IDE ............................. 123

Compiling and linking a DLL from the commandline .................... 123

Module definition files . . . . . . . . . .. 124

Import libraries . . . . . . . . . . . . . . . .. 124

Creating DLLs . . . . . . . . . . . . . . . . . . .. 125

LibMain and WEP .............. 125

Pointers ill:ld memory . . . . . . . . . . .. 126

Static data in DLLs ............ 127

C++ classes and pointers . . . . . . . .. 127

Chapter 4 Managing multi-file projects

131

Using the project manager ........... 132

Error tracking ...................... 135

Stopping a make . . . . . . . . . . . . . . . . .. 136

Syntax errors in multiple source files . 136

Saving or deleting messages . . . . . . .. 137

The power of the Project Manager . . . .. 137

Autodependency checking ......... 138

Using different file translators ........ 138

Overriding libraries ................. 141

More Project Manager features ....... 141

Looking at files in a project ......... 143

Notes for your project ............. 144

Chapter 5 The editor from A to Z

145

The new and the old. . . . . . . . . . . . . . . .. 145

Editor reference .................... 146

Jumping around .................. 148

Block commands. . . . . . . . . . . . . . . . .. 148

Other editing commands . . . . . . . . . .. 150

Search and replace ................ 151

Searching and searching again . . .. 151

Search and replace .............. 152

Pair matching .................... 152

Directional and nondirectional matching ... -. . . . . . . . . . . . . . . . . .. 153

Nestable delimiters. . . . . . . . . . .. 154

Comment delimiters .......... 154

Chapter 6 The command-line compiler

157

Using the command-line compiler ..... 158

Running in real mode ............. 158

Running in protected mode ........ 158

Using the options ................. 159

Option precedence rules ......... 160

Syntax and file names ............. 163

Response files .................... 163

Configuration files ................ 164

Option precedence rules ......... 164 iii

Compiler options ................... 165

Memory model ................... 166

Macro definitions ................. 167

Code generation options ........... 167

The -v and -vi options. . . . . . . . . .. 171

Optimization options .............. 172

Source code options ............... 173

Error-reporting options ............ 174

ANSI violations . . . . . . . . . . . . . .. 175

Frequent errors ............... 175

Portability warnings ........... 176

C++ warnings ................ 176

Segment-naming control ....... . . .. 177

Compilation control options . . . . . . .. 178

EMS and extended memory options . 180

C++ virtual tables . . . . . . . . . . . . . . . .. 182

Linker options . . . . . . . . . . . . . . . . . . . . .. 183

Environment options ................ 183

Searching for include and library files ............................. 184

File-search algorithms ............. 185

An annotated example ........... 186

Chapter 7 Utilities

189

IMPDEF (module definition files) ..... 190

IMPLIB (import libraries) ............ 192

Re-creating IMPORT. LIB . . . . . . . . . .. 193

MAKE: The program manager . . . . . . .. 193

How MAKE works . . . . . . . . . . . . . . .. 194

Starting MAKE ................... 195

The BUlL TINS.MAK file ......... 196

Command-line options .......... 196

A simple use of MAKE ............ 197

Creating makefiles ................ 200

Components of a makefile . . . . . . . . .. 200

Comments ..................... 201

Command lists ................... 201

Prefixes . . . . . . . . . . . . . . . . . . . . .. 202

Command body .............. 202

Batching programs ............ 203

Executing DOS commands ..... 205

Explicit rules ................... 206

Special considerations ......... 207

Examples .................... 207

Automatic dependency checking . . . . . . . . . . . . . . . . . . . .. 208

Implicit rules ... . . . . . . . . . . . . . . .. 208

Macros ........................ 211

Defining macros .............. 212

Using macros. . . . . . . . . . . . . . . .. 212

Special considerations ......... 212

Predefined macros ............ 213

File name macros ............. 214

Directives ........................ 215

Dot directives .................. 216

.path.ext .....................

216

File-inclusion directive .......... 217

Conditional execution directives .. 218

Expressions allowed in conditional directives .................... 219

. Error directive . . . . . . . . . . . . . . . . .. 220

Macro undefinition directive ..... 221

MAKE errors . . . . . . . . . . . . . . . . . . . .. 221

TLIB: The Turbo Librarian ........... 225

Why use object module libraries? ... 225

The TLIB command line ........... 226

The operation list ............... 227

File and module names ........ 227

TLIB operations. . . . . . . . . . . . . .. 227

Using response files ............... 228

Creating an extended dictionary: The IE option ........................... 229

Setting the page size: The

option . 229

Advanced operation: The

C option . 230

Examples ........................ 231

TLINK (linker) ..................... 231

Invoking TLINK ..... . . .. . . . . . . . .. 232

An example of linking for DOS ... 233

An example of linking for Windows .......................... 233

File names on the TLINK command line ........................... 233

Using response files ............. 235

The TLINK configuration file ..... 236

Using TLINK with Borland C++ modules ....................... 236

Startup code ................. 237

Libraries . . . . . . . . . . . . . . . . . . . .. 238 iv

Using TLINK with BCC . . . . . . . . .. 240

TLINK options ................... 241

The TLINK configuration file ..... 241

/3 (80386 32-bit code) ............ 241

/ A (align segments) ............. 242

/c (case sensitivity) .............. 242

/C (case sensitive exports) ....... 242

/ d (duplicate symbols) .......... 242

/e (no extended dictionary) ...... 243

/i (uninitialized trailing segments) .243

(line numbers) ................ 243

/L (library search paths) ......... 244

/m, Is, and /x (map options) ..... 244

/n (ignore default libraries) ...... 246

(overlays) ................... 246

/P (pack code segments) ......... 247

/t (tiny model.COM file) ........ 247

/Td and /Tw (target options) ..... 248

/v (debugging information) ...... 248

/ y (expanded or extended memory) . . . . . . . . . . . . . . . . . . . . . .. 249

Restrictions .................... 249

The module definition file .......... 250

Module definition file defaults . . .. 250

A quick example . . . . . . . . . . . . . . .. 251

Module definition reference ........ 252

CODE ......................... 252

DATA ......................... 253

DESCRIPTION ................. 254

EXETYPE ....... . . . . . . . . . . . . . .. 254

EXPORTS. . . . . . . . . . . . . . . . . . . . .. 254

HEAPSIZE ..................... 255

IMPORTS. . . . . . . . . . . . . . . . . . . . .. 255

LIBRARY .................. . . .. 256

NAME ........................ 256

SEC;MENTS .................... 257

STACKSIZE .. .. . . .. .. .. . .. . .. .. 258

STUB .......................... 258

TLINK messages . . . . . . . . . . . . . . . . .. 258

Appendix A Precompiled headers

271

How they work . . . . . . . . . . . . . . . . . . . .. 271

Drawbacks . . . . . . . . . . . . . . . . . . . . . .. 272

Using precompiled headers .......... 272

Setting file names ................. 273

Establishing identity .............. 273

Optimizing precompiled headers 274

Index

277 v

T A B L E s

1.1: General hot keys ................... 10

1.2: Menu hot keys .................... 11

1.3: Editing hot keys ................... 11

1.4: Window management hot keys ...... 12

1.5: Online Help hot keys .............. 12

1.6:

Debugging/Running hot keys ....... 12

1.7:

Manipulating windows ............ 15

2.1: Get Info settings ................... 32

2.2: Format specifiers recognized in debugger expressions .............. 53

3.1: Compiler options and the

_export

keyword ........................ 115

3.2: Startup and library files for DLLs ... 118

3.3: Resource Compiler options ........ 122

5.1: Full summary of editor commands .. 146

5.2: Block commands in depth ......... 149

5.3: Other editor commands in depth ... 150

5.4: Delimiter pairs ................... 154

6.1: Command-line options summary ... 160

7.1: IMPLIB options .................. 193

7.2: MAKE options ................... 197

7.3: MAKE prefixes ................... 202

7.4: MAKE macros ................... 213

7.5: MAKE directives ................. 215

7.6: MAKE operators ................. 220

7.7: TLIB options ..................... 226

7.8: TLIB action symbols .............. 228

7.9: TLINK options ................... 232

7.10: DOS application .OBJ and .LIB files .239

7.11: Windows application .OBJ and .LIB files ............................ 240

7.12: DLL object and library files ....... 240

7.13: TLINK overlay options ........... 246 vi

G u

E s

1.1: A typical window ................. 14

1.2: A typical status line ................

1.3: A sample dialog box ............... 17

2.1:

2.2: The Save File As dialog box ......... 30

2.3: The Change Directory dialog box .... 31

2.4: The Get Info box .................. 32

2.5: The Find dialog box ................

2.6: The Replace dialog box ............. 39

2.7:

The Go to Line Number dialog box . .40

2.8:

The Locate Function dialog box .....

2.9:

The Arguments dialog box .......... 44

2.10: The Evaluate/Modify dialog box ... 50

2.11: The Breakpoints dialog box ........ 55

2.12:

The Breakpoint Modify /New dialog box ............................. 56

2.13:

The Project File dialog box .........

2.14: The Add Item to Project List dialog box ............................. 58

2.15:

The Override Options dialog box ...

2.16: The Include Files dialog box ........ 60

2.17:

The Code Generation dialog box ....

2.18:

The Advanced Code Generation dialog box .............................

2.19: The Entry/Exit Code dialog box .... 65

2.20:

The C++ options dialog box ........

2.21:

The Optimizations Options dialog box .............................

2.22: The Source Options dialog box ..... 69

2.23: The Compiler Messages dialog box .70

2.24: The Portability warnings dialog box

.71

2.25: The ANSI Violations dialog box .... 72

2.26:

The More ANSI Violations dialog box ............................. 72

2.27:

The C++ Warnings dialog box ......

2.28: The Frequent Errors dialog box ..... 73

2.29:

The More Frequent Errors dialog box .............................

2.30:

The Segment Names dialog box ....

2.31:

The Transfer dialog box ...........

2.32:

The Modify/New Transfer Item dialog box .............................

2.33:

The Make dialog box ..............

2.34: The Linker dialog box ............. 84

2.35:

Set Application Options ...........

2.36: The Debugger dialog box .......... 87

2.37:

The Directories dialog box .........

2.38:

The Preferences dialog box ........

3.1: Compiling and linking a Windows program ..........................

104

5.1:

Search for match to square bracket or parenthesis ......................

154

5.2: Forward search I ................. 155

5.3: Forward search II ................. 155

5.4:

Backward search .................

156

7.1: Detailed map of segments ......... 245 vii

N T R o

D u c

T o

If you haven't already done so, read the introduction, Chapter 1

("Installing Borland C++"), and Chapter 2 ("Navigating the

Borland C++ manuals") in

Getting Started

for information on the overall organization of the Borland C++ manuals. Those chapters tell you about many of the highlights of Borland C++, how to install Borland C++, and how to use the manuals most effectively.

This book, the

User's Guide,

contains reference-style information on the Programmer's Platform (the IDE), using Borland C++ to write a Windows application, the Project Manager, the integrated editor, the command-line compiler, and some of the many utilities included with Borland C++. See the introduction and Chapter 2,

"Navigating the Borland C++ manuals," in

Getting Started

for information on how to most effectively use the Borland C++ documentation set.

Here is a breakdown of the chapters in this book:

Chapter 1: The Programmer's Platform

introduces the features of the Programmer's Platform, giving information and examples of how to use the IDE to full advantage.

It includes information on how to start up and exit from the IDE.

Chapter 2: Menus and options reference

provides a complete reference to the menus and options of the IDE.

Chapter 3: Building a Windows application

tells you what you need and how to pull it together to write an application for

Microsoft's Windows.

Chapter 4: Managing multi-file projects

tells how to use the

Project Manager to manage multi-file projects.

Chapter 5: The editor from A to Z

provides a complete reference to the editor.

Chapter 6: The command-line compiler

tells how to use the command-line compiler. It also explains configuration files.

Introduction

Chapter 7: Utilities

describes some of the utility programs that come with Borland C++.

Appendix A: Precompiled headers

describes some of the utility programs that come with Borland C++.

Typefaces used in this book

The typefaces used in this manual are described in

Getting Started.

Borland

C++

User's Guide

H A p

T E R

The Programmer's Platform

Borland's Programmer's Platform, also known as the integrated development environment or IDE for short, has everything you need to write, edit, compile, link, and debug your programs. For example, it provides

II multiple, movable, resizable windows

• mouse support

• dialog boxes

• cut-and-paste and cut-and-paste commands

• full editor undo and redo

• examples ready to copy from Help

• a built-in assembler

• quick transfer to other programs (like T ASM) and back again

• an editor macro language

The IDE runs in two modes: protected and real. Under "Starting up and exiting," you'll find a description of how to start up the

IDE in either mode, and what the differences are. Since the IDE works the same in either mode, this chapter, and Chapter 2 (the menu reference) don't address the differences and the implications for your programs.

This chapter is divided into two main sections: "Starting up and exiting" tells you how to enter and exit the IDE; "The components," starting on page 8, discusses the generic compo-

Chapter

The Programmer's Platform

nents that comprise the IDE. Chapter 2, starting on page 25, provides a reference to each menu item and dialog box.

Starting up and exiting

You can run the IDE in either real or protected mode. You can use protected mode if you have a 286, 386, or i486 machine with 640K of conventional RAM and at least 576K of extended or (simulated or real) expanded memory. Otherwise, use real mode.

Note that, although you may be running Borland C++ in protected mode, you are still generating applications to run in real mode. The greatest advantages to using Borland C++ in protected mode are:

• both the compiler and your application have

much

more room to run than if you were running Borland C++ in real mode

• the linker runs faster

Running in real mode

To invoke the IDE in real mode, type

Be at the DOS prompt; you can follow it with one or more options.

Running in protected mode

Running Borland C++ in protected mode requires a small amount of preparation. It involves interaction between three files:

BCX.EXE, BCX.OVY, and TKERNEL.EXE. BCX.EXE loads

TKERNEL and BCX.OVY, which is the protected-mode version of the IDE. Although BCX.EXE loads these files automatically, so that you don't need to be concerned with invoking them yourself, they do both need to be on the path or in the BCX.EXE startup directory so it can find them.

Once you've verified that the correct directories are on the path, running Borland C++ in protected mode is as simple as running it in real mode; the syntax is identical except for using BCX in the place ofBC. .

The options and menus are identical to those for BC; therefore, for the remainder of this chapter, when we mention the IDE we mean both BC and BCX (unless specifically called out otherwise).

Borland

C++

User's Guide

. . BCX.EXE loads TKERNEL each time you invoke BCX. You can save some loading time by preloading TKERNEL; before rwming

BCX, type

TKERNEL hi=yes on the DOS command line. This has the added benefit of storing most of TKERNEL in extended memory, freeing more conventional memory for your application. When you are through with your Borland c++ session, type

TKERNEL rem to remove TKERNEL.

Windows and protected mode

You can a/so run the protected mode versions of the command-line compiler and TLINK under Windows using the same procedure.

You can use the protected mode version of the IDE while rwming

Windows. To do so, first load TKERNEL.EXE with the command:

TKERNEL hi=yes kilos=nnnn where

nnnn

is the number of Kbytes to be managed by the kernel.

We suggest kilos=2048. The remaining extended memory is available for Windows and other programs. Then run Windows in standard mode (type the command

WIN / s). With Windows in standard mode, you can't run the IDE in a virtualized DOS window, but only as a full screen.

You can only run the protected mode IDE in Windows standard or real mode, 'not in enhanced mode.

Command-line options

The command-line options for Borland C++'s IDE are: fb,

Id, Ie,

/h,

II, 1m, Ip, Irx, Is,

and

Ix.

These options use this syntax:

BC I BCX

[option [option ... ]] [sourcename

projectname [sourcename]]

where

sourcename

is any ASCII file (default extension assumed),

projectname

is your project file (it

must

have the .PRJ extension), and

option

can be one or more of the options.

The /b option

The fb option causes Borland C++ to recompile and link all the files in your project, print the compiler messages to the standard output device, and then return to the operating system. This option allows you to invoke Borland C++ from a batch file so you can automate builds of projects. Before the build, Borland C++ will load a default project file or one given on the command line.

Chapter

The Programmer's Platform

Borland C++ determines what .EXE to build based on the project file or the file currently loaded in the Editor if no project file is found.

Enter the

BC or

BCX command with either

Ib

alone or the project file name followed by

lb. For example,

Be /b

Be myproj.prj /b

Unless a project file is loaded, you can specify the name of a program to be compiled and linked on the command line. Type in the program name after the

BC or

BCX command, followed by

/b:

Be myprog /b

The /d option The

option causes Borland C++ to work in dual monitor mode if it detects appropriate hardware (for example, a monochrome card and a color card); otherwise, the /d option is ignored. Use dual monitor mode when you run or debug a program, or shell to

DOS (File I DOS Shell).

If your system has two monitors, DOS treats one monitor as the active monitor. Use the DOS MODE command to switch between the two monitors

(MODE coao, for example, or

MODE MONO).

In dual monitor mode, the normal Borland C++ screen will appear on the inactive monitor, and program output will go to the active monitor. So when you type

BC / d or

BCX / d at the DOS prompt on one monitor, Borland C++ will come up on the other monitor.

When you want to test your program on a particular monitor, exit

Borland C++, switch the active monitor to the one you want to test with, and then issue the

BC / d or

BCX / d command again. Program output will then go to the monitor where you typed the

BC or

BCX command.

Keep the following in mind when using the

option:

• Don't change the active monitor (by using the DOS MODE command, for example) while you are in a DOS shell (File I DOS

Shell).

• User programs that directly access ports on the inactive monitor's video card are not supported, and can cause unpredictable results.

• When you run or debug programs that explicitly make use of dual monitors, do not use the Borland C++ dual monitor option

(ld).

Borland

C++

User's Guide

The /e and /x options

Of the three options,

Ie, Ix, and

Irx, Ix is the best to use, followed by

Ie, with

Irx the third best.

Normally, Turbo C++ swaps to a hard disk when allocating memory. The / e option tells Borland C++ to swap to expanded memory, the / x option tells Borland C++ to swap to extended memory .

The / e option is enabled by default. The syntax for these two options is as follows:

/e[=n]

where

n

equals the number of pages of expanded memory that you want the IDE to use for swapping. A page is 16K.

/x[=[r][,n]]

where

n

is the number of kilobytes of extended memory that you want the IDE to use for swapping and

is the number of kilobytes of extended memory to reserve for other programs.

. . You can also use these options with the protected-mode version of the IDE (BCX). If you are using simulated EMS (such as that provided by QEMM or 386

MAX),

BCX will also use the simulated

EMS; use the

Ix

option.

The /h option If you type

BC/h or

BCX/h on the command line, you'll get a list of all the command-line options available. Their default values will also be shown.

The /1 option

Use the

option if you're running Borland C++ on an LCD screen.

The /m option The

option lets you do a make rather than a build (that is, only outdated source files in your project are recompiled and linked).

Follow the instructions for the

option, but use 1m instead.

The /p option

Use the

option, which controls palette swapping on EGA video adapters, when your program modifies the EGA palette registers.

The EGA palette will be restored each time the screen is swapped.

In general, you don't need to use this option unless your program modifies the EGA palette registers or unless your program uses

BGI to change the palette:

Chapter

The Programmer's Platform

The /r option

Use the

Irx

option if all your extended or expanded memory has been allocated to a RAM disk. The

x

Irx

is the letter of the "fast" swap drive. For example,

Ird

will use drive D as the swap drive.

This option is primarily for when you have committed all your extended or expanded memory to a RAM disk for other purposes.

Exiting Borland

C++

There are three ways to leave the IDE.

You return to the IDE affer you exit the program you transferred to.

• The first method exits the IDE "permanently;" you have to type '

BC or

BCX again to reenter it. To exit this way, choose File

Quit

(or press

Alt-X).

If you've made changes that you haven't saved, you'll see a prompt asking if you want to save your programs before exiting.

• The next method allows you to shell out from the IDE to enter commands at the DOS command line. To use this method, choose File

DOS Shell. You can enter any normal DOS commands, and you can even run other programs from the command line. When you're ready to return to the IDE, type

EXIT at the command line and press

Enter.

The IDE reappears just as you left it.

• The third method lets you temporarily transfer to another program without leaving the IDE. To do so, choose a program from the :: menu. If there are no programs installed on this menu, you can add some with the Options I Transfer command.

The components

There are three visible components to the IDE: the menu bar at the top, the window area in the middle, and the status line at the bottom. Many menu items also offer dialog boxes. Before we describe each menu item in the IDE, we'll explain these more generic components.

The menu bar and menus

The menu bar is your primary access to all the menu commands.

The only time the menu bar is not visible is when you're viewing your program's output or transferring to another program. You'll

8 Borland

C++

User's Guide

see a highlighted menu title when the menu bar is active; that menu title is the currently selected menu.

If a menu command is followed by an ellipsis ( ... ), choosing the command displays a dialog box.

If the command is followed by an arrow

(~), the command leads to another menu (a pop-up menu).

If the command has neither an ellipsis nor an arrow, the action occurs as soon as you choose the command.

Here is how you choose menu commands using just the keyboard:

To cancel an action, press Esc.

Press

F10.

This makes the menu bar active; the next thing you type will relate to the items on the menu bar.

2. Use the arrow keys to select the menu you want to display.

Then press

Enter.

As a shortcut for this step, you can just press the highlighted letter of the menu title. For example, from the menu bar, press

E to move to and display the Edit menu. From anywhere, press

Alt

and the highlighted letter (such as

Alt-E)

to display the menu you want.

3. Use the arrow keys again to select the command you want.

Then press

Enter.

Again, as a shortcut, you can just press the highlighted letter of a command to choose it once the menu is displayed.

At this point, Borland C++ either carries out the command, displays a dialog box, or displays another menu.

Borland

C++

uses only the left mouse button. You can, however, customize the right button and make other mouse option changes, by choosing Options I Mouse

(see page 90).

You can also use a mouse to choose commands.

1. Click the desired menu title to display the menu.

2. Click the desired command.

Or, drag straight from the menu title down to the menu command. Release the mouse button on the command you want.

(If you change your mind, just drag off the menu; no command will be chosen.)

Note that some menu commands are unavailable when it would make no sense to choose them. However, you can still get online help about currently unavailable commands.

Chapter

The Programmer's Platform

Shortcuts Borland C++ offers a number of quick ways to choose menu commands. (For example, the click-drag method for mouse users.)

From the keyboard, you can use a number of keyboard shortcuts

(or

hot keys)

to access the menu bar and choose commands. Shortcuts for dialog boxes work just as they do in a menu. (But be aware that you need to hold down

Alt

while pressing the highlighted letter when moving from an input box to a group of buttons or boxes.) Here's a list of the shortcuts available:

Do this ...

Press

Aft

plus the highlighted letter of the command Gust press the highlighted letter in a dialog box). For the

:: menu, press

Alt-Spacebar.

Type the keystrokes next to a menu command.

To accomplish this ...

Display the menu or carry out the command.

Carry out the command.

For example, to cut selected text, press

Alt-E T

(for Edit I Cut) or you can just press

Shift-Del,

the shortcut displayed next to it.

Many menu items have corresponding

hot keys;

one- or two-key shortcuts that immediately activate that command or dialog box.

The following table lists the most-used Borland C++ hot keys.

Table 1.1

General hot keys

F5

F6

F7

FB

F9

F10

Key(s)

F1

F2

F3

F4

Menu item

Help

File I Save

File I Open

Run I Go to Cursor

Window I Zoom

Window I Next

Run I Trace Into

Run I Step Over

Compile I

Make EXE File

(none)

Function

Displays a help screen.

Saves the file that's in the active

Edit window.

Brings up a dialog box so you can open a file.

Runs your program to the line where the cursor is positioned.

Zooms the active window.

Cycles through all open windows.

Runs your program in debug mode, tracing into functions.

Runs your program in debug mode, stepping over function calls.

Invokes the Project Manager to make an .EXE file.

Takes you to the menu bar.

Borland

C++

User's Guide

Table 1.1: General hot keys (continued)

Table 1.2

Menu hot keys

Key(s)

Aft-Spacebar

AIt-C

AIt-D

AIt-E

AIt-F

Aft-H

AIt-O

Alt-P

AIt-R

AIt-S

AIt-W

AIt-X

Menu item

==menu

Compile menu

Debug menu

Edit menu

File menu

Help menu

Options menu

Project menu

Run menu

Search menu

Window menu

File I Quit

Function

Takes you to the == (System) menu

Takes you to the Compile menu

Takes you to the Debug menu

Takes you to the Edit menu

Takes you to the File menu

Takes you to the Help menu

Takes you to the Options menu

Takes you to the Project menu

Takes you to the Run menu

Takes you to the Search menu

Takes you to the Window menu

Exits Borland C++ to DOS

Table 1.3

Editing hot keys

Key(s)

Clrl-Del

Clr/-Ins

Shift-Del

Shift-Ins

Alt-Bkspc

Ctrl-L

Menu item Function

Edit I Clear

Edit I Copy

Edit I Cut

Removes selected text from the window and doesn't put it in the

Clipboard

Copies selected text to Clipboard

Places selected text in the

Edit I Paste

File I Save

Clipboard, deletes selection

Pastes text from the Clipboard into

Edit I Undo the active window

Restores the text in the active window to a previous state.

Search I Search Again Repeats last Find or Replace command

Saves the file in the active Edit

File I Open window

Lets you open a file

Chapter

The Programmer's Platform

Table 1.3: Editing hot keys (continued)

Table 1.4

Window management hot keys

Key(s)

AIt-#

Alt-O

AIt-F3

Alt-F4

Alt-FS

Ctrl-FS

Menu item Function

Window I Next

Displays a window, where # is the number of the window you want to view

Window I List

Window I Close

Debug I Inspect

Displays a list of open windows

Closes the active window

Opens an Inspector window

Window I User Screen Displays User Screen

Window I Zoom Zooms/ unzooms the active window

Switches the active window

Changes size or position of active window

Table 1.5

Online Help hot keys

Key(s)

F1 F1

Shift-F1

Aft-F1

Ctrl-F1

Menu item Function

Help

Contents Opens a context-sensitive help screen

Brings up Help on Help. Gust press

when you're already in the help system.)

Help I Index Brings up Help index

Help I Previous Topic Displays previous Help screen

Help I Topic Search Calls up language-specific help in

Editor only

Table 1.6

Debugging/Running hot keys

Key(s) Menu item

Alt-F4

Aft-Fl

Aft-F8

Aft-F9

Ctrl-F2

Ctrl·F3

Ctrl-F4

Ctrl·F7

Ctr/-F8

Ctrl-F9

Debug

I Inspect

Previous Error

Next Error

Function

Opens an Inspector window

Takes you to previous error

Takes you to next error

Compile I Compile to OBI Compiles to .OBJ

Run I Program Reset Resets running program

Debug I Call Stack Brings up call stack

Debug

Evaluate/Modify Evaluates an expression

Debug I Add Watch Adds a watch expression

Debug I Toggle Breakpoint Sets or dears conditional breakpoint

Run I Run

Run I Go To Cursor

Run I Trace Into

Runs program

Runs program to cursor position

Executes tracing into functions

Run I Step Over

Executes skipping function calls

Compile I Make EXE File

Makes (compiles/links) program

Borland

C++

User's Guide

Borland C++ windows

Most of what you see and do in the IDE happens in a

window.

A window is a screen area that you can open, close, move, resize, zoom, tile, and overlap.

If you exit Borland C++ with a

file open in

window, you are returned to your desktop, open file and all, when you

next use Borland C++.

You can have many windows open in the IDE, but only one window can be

active

at any time. The active window is the one that you're currently working in. Any command you choose or text you type generally applies only to the active window. (If you have the same file open in several windows, the action will apply to the file everywhere that it's open.)

You can spot the active window easily: It's the one with the double-lined border around it. The active window always has a close box, a zoom box, and scroll bars. If your windows are overlapping, the active window is always the one on "top" of all the others (the frontmost one).

There are several types of windows, but most of them have these things in common:

13 a title bar

.. a close box

• scroll bars

.azoom box

• a window number (1 to 9)

The Edit window also displays the current line and column numbers in the lower left comer. If you've modified your file, an asterisk (*) will appear to the left of the column and line numbers.

This is what a typical window looks like:

Chapter

The Programmer's Platform

Figure 1.2

A typical window

The lIIII!I!li contai ns the name of the wi ndow.

Cl ick the

~to quickly close the window.

I

T " "

[1]=======

Window Title

= = = = = = : =[t]~

I ...

The first nine

~: ~::-:~t~

Use a mouse to scroll the contents of the wi ndow

Drag any corner to make windows larger or smaller

Shortcut: Aft-Spacebar invokes theEimenu.

The

close box

of a window is the box in the upper left comer. Click this box to quickly close the window. (Or choose Window I Close or press

Alt-F3.)

The Inspector and Help windows are considered temporary; you can close them by pressing

Esc.

The

title bar,

the topmost horizontal bar of a window, contains the name of the window and the window number. Double-clicking the title bar zooms the window. You can also drag the title bar to move the window around.

Shortcut: Double-click the title bar

of a window to zoom

or restore it.

The

zoom box

of a window appears in the upper right comer. If the icon in that comer is an up arrow (t), you can click the arrow to enlarge the window to the largest size possible.

1£ the icon is a doubleheaded arrow

(~), the window is already at its maximum size. In that case, clicking it returns the window to its previous size. To zoom a window from the keyboard, choose Window I

Zoom, or press

F5.

Borland

C++

User's Guide

The first nine windows you open in Borland c++ have a

window number

in the upper right border.

Alt-O

gives you a list of all windows you have open. You can make a window active (and thereby bring it to the top of the heap) by pressing

Alt

in combination with the window number. For example, if the Help window is #5 but has gotten buried under the other windows,

Alt-5

brings it to the front.

Scroll bars

are horizontal or vertical bars that look like this:

~ 111I11I"1'1I11I1"11I1"11"11111'1I11I11I11I'1I11I11I"I'CII"'U'1I11I11I1

. . . ItIIlIIl.II.IIIIIIII.III.IIIIII .... I . . IIIIII . . . . . . I . . III . . . IIII . . III . . . .

11111 . . . . . . . 11111 . . . . . . . . . . . . . . . . . . 1 . . . . . . . . ""11111

. . . . 111 . . . . 11111 . . 11 . . . . . . . . . . . . . . 1111 . . . . . . . . . . . . . . . . . . . . . . . . . . 11111 . . . . . . . . . . . . . . 111 . . ' . . . . . . . . 111 . . 111111 . . . . 11111.111111111 . . . . . . . . 111,,,1.11 .. 1 . . .

Scroll bars also show you where you are in your file.

0..

You use these bars with a mouse to scroll the contents of the window. Click the arrow at either end to scroll one line at a time.

(Keep the mouse button pressed to scroll continuously.) You can click the shaded area to either side of the scroll box to scroll a page at a time. Finally, you can drag the scroll box to any spot on the bar to quickly move to a spot in the window relative to the position of the scroll box.

You can drag any comer to make a window larger or smaller. To resize using the keyboard, choose Size/Move from the Window menu, or press

Ctrl-F5.

Window management

Table 1.7 gives you a quick rundown of how to handle windows in Borland C++. Note that you don't need a mouse to perform these actions-a keyboard works just fine.

Table 1.7

Manipulating windows

To accomplish this:

-----------------------------------------------------

Open an Edit window

Use one of these methods

Choose File I Open to open a file and display it in a window, or press

F3.

Open other windows

Close a window

Activate a window

Choose the desired window from the

Window menu

Choose Close from the Window menu (or press

Alt-F3),

or click the close box of the window.

Click anywhere in the window, or

Press

Aft

plus the window number (1 to 9, in the upper right border of the window), or

Chapter

The Programmer's Platform

Table 1.7: Manipulating windows (continued)

Move the active window

Resize the active window

Zoom the active window

Choose Window I List or press

A/t-O

and select the window from the list, or

Choose Window I Next or

to make the next window active (next in the order you first opened them).

Drag its title bar, or press

Ctrl-F5

(Window I

Size/Move) and use the arrow keys to place the window where you want it, then press

Enter.

Drag any comer. Or choose Window I

Size/Move and press

Shift

while you use the arrow keys to resize the window, then press

Enter.

The shortcut is to press

Ctrl-F5

and then use

Shift

and the arrow keys.

Click the zoom box in the upper right corner of the window, or

Double-click the window's title bar, or

Choose Window I Zoom, or press

F5.

The status line

Figure 1.3

A typical status line

The status line appears at the bottom of the screen; it

• reminds you of basic keystrokes and shortcuts (or hot keys) applicable at that moment in the active window .

• lets you click the shortcuts to carry out the action instead of choosing the command from the menu or pressing the shortcut keystroke.

• tells you what the program is doing. For example, it displays

"Savingfilename ... "

when an Edit file is being saved.

• offers one-line hints on any selected menu command and dialog box items.

The status line changes as you switch windows or activities. One of the most common status lines is the one you see when you're actually writing and editing programs in an Edit window. Here is what it looks like:

Fl Help F2 Save F3 Open F7 Trace Fa Step F9 Make FlO Menu

Borland

C++

User's Guide

When you've selected a menu title or command, the status line changes to display a one-line summary of the function of the selected item. For example, if the Options menu title is selected

(highlighted), the status line reads "Set defaults for IDE, compiler, debugger; define transfer programs." Similarly, when the Edit

Cut command is selected, the status line reads "Remove the selected text and put it in the Clipboard."

Dialog boxes

If a menu command has an ellipsis after it ( ... ), the command opens a

dialog box.

A dialog box is a convenient way to view and set multiple options. When you're making settings in dialog boxes, you work with five basic types of onscreen controls: radio buttons, check boxes, action buttons, input boxes, and list boxes.

Here's a sample dialog box that illustrates some of these items:

Figure 1.4

A sample dialog box

If you have a color monitor,

Borland C++ uses different

colors for various elements of the dialog box.

This dialog box has three standard buttons: OK, Cancel, and Help.

If you choose OK, the choices in the dialog box are made; if you choose Cancel, nothing changes and no action is made, but the dialog box is put away. Choose Help to open a Help window about this dialog box.

Esc

is always a keyboard shortcut for

Cancel (even if no Cancel button appears).

If you're using a mouse, click the button you want. When you're using the keyboard, press

Alt

and the highlighted letter of an item to activate it. For example,

Alt-K

selects the OK button. Press

Tab

Shift-Tab

to move forward or back from one item to another in a dialog box. Each element is highlighted when it becomes active.

In this dialog box, OK is the

default button,

which means you need only press

Enter

to choose that button. (On monochrome systems, arrows indicate the default; on color monitors, default buttons are

Chapter

The Programmer's Platform

18 highlighted.) You can select another button with

Tab;

press

Enterto

choose that button. Be aware that tabbing to a button makes that button the default.

Check boxes and radio buttons

[Xl Checked check box

[ ] Unchecked check box

The dialog box also has

check boxes.

When you select a check box, an

x

appears in it to show you it's on. An empty box indicates it's off. To set a check box to on, click it or its text, by pressing

Tab

until the check box is highlighted and then pressing

Spacebar,

or by selecting

Aft

and the highlighted letter. You can have any number of check boxes checked at any time.

If several check boxes apply to a topic, they appear as a group. In that case, tabbing moves to the group. Once the group is selected, use the arrow keys to select the item you want, and then press

Spacebar

to choose it.

On monochrome monitors, the active check box or group of check boxes will have a chevron symbol (») to the left and right. When you press

Tab,

the chevrons move to the next group of checkboxes or radio buttons. e )

None ee)

Emulation e )

8087

The dialog box also has

radio buttons.

Radio buttons are so called because they act just like the buttons on a car radio. There is always one-and only one-button pushed in at a time. Push one in, and the one that was in pops out.

Radio buttons differ from check boxes in that they present mutually exclusive choices. For this reason, radio buttons always come in groups, and exactly one (no more, no less) radio button can be on in anyone group at anyone time. To choose a radio button, click it or its text. From the keyboard, select

Aft

and the highlighted letter, or press

Tab

until the group is highlighted and then use the arrow keys to choose a particular radio button. Press

Tab

Shift-Tab

again to leave the group with the new radio button chosen. The column to the left gives an example a a set of radio buttons.

Input boxes and lists

Dialog boxes can also contain input boxes, which allow you to type in text. Most basic text-editing keys work in the text box (for example, arrow keys,

Home, End,

and insert/overwrite toggles by

Ins).

If you continue to type once you reach the end of the box, the contents automatically scroll. If there's more text than what shows in the box, arrowheads appear at the end

(~and ~).

You can click the arrowheads to scroll or drag the text. If you need to enter control characters (such as AL or AM) in the input box, then prefix

Borland

C++

User's Guide

the character with a AP. So, for example, entering APAL enters a

AL into the input box. (This ability is useful for search strings.)

You can control whether history lists are saved to the desktop using Options I

Environment I Desktop.

If an input box has a down-arrow icon to its right, there is a

history list

associated with that input box. Press

Enter

to select an item from this list. In the list you'll find text you typed into this box the last few times you used this dialog box. The Find box, for example, has such a history list, which keeps track of the text you searched for previously. If you want to reenter text that you already entered, press J, or click the t icon. You can also edit an entry in the history list. Press

Esc

to exit from the history list without making a selection.

Here is what a history list for the

Fin~ text box might look like if you had used it seven times previously: struct date printf(1I printf( char buf[7]

/* return (0 return

A final component of many dialog boxes is a

list box.

A list box lets you scroll through and select from variable-length lists (often file names) without leaving a dialog box. If a blinking cursor appears in the list box and you know what you're looking for, you can type the word (or the first few letters of the word) and

Borland C++ will search for it.

You make a list box active by clicking it or by choosing the highlighted letter of the list title (or press

Tab

until it's highlighted).

Once a list box is displayed, you can use the scroll box to move through the list or press t or J, from the keyboard.

Editing

If you're a longtime user of Borland products, the following summary of our major editing features can help you identify the areas that are different from our older products .

• multi-file capabilities let you open several files at once

Chapter

The Programmer's Platform

• multiple windows let you have several views onto the same file or different files

• block mode that is switchable between persistent and destructive (see page 93)

• mouse support

• support for large files (greater than

64K; limited to

8 megabytes for all edit windows combined)

• Shift

i J.

• edit windows that you can move, resize, or overlap

• a sophisticated macro language, so you can create your own editor commands (documented online)

• a built-in assembler and support for inline assembler code

• an undo and redo feature with an extensive buffer

• the ability to paste examples from the Help window

• an editable Clipboard that allows cutting, copying, and pasting in or between windows

• a Transfer function that lets you run other programs and capture output to an editor without leaving Borland C++

Project and configuration files

The

IDE handles configuration files differently than Turbo C. The focus of the

IDE has changed from configuration-based to project-based. This means that instead of loading a configuration

C.TC) file that defines your project, you load a project file that contains everything needed to build your program.

Turbo C files In Turbo C, all options (compiler, environment, and so on) are stored in the .TC file. The project file consists of an ASCII list of file names that comprise the project. Thus, the information needed to build the program that the project represents is spread across two files: the project file and the .TC file.

Borland C++ project files

The IDE places all information needed to build a program into a binary project file. This includes compiler and linker options, directory paths, project specific settings (for example, program heap size, autodependencies used, and so on), and special translators (such as TASM). In addition, the project file contains other general information on the project, such as compilation statistics (shown in the project window), and cached auto-

Borland

C++

User's Guide

dependency information. Chapter 4, "Managing multi-file projects," covers project files and the Project Manager in depth.

Configuration files

The TCCONFIG.TC file contains only environmental (or global) information; project files (.PRJ) now contain information on all other settings and options except those shown in the following list. For instance, the TCCONFIG.TC file knows whether to save breakpoints and watchpoints, but, if activated, the breakpoints and watchpoints themselves will be saved in the .PRJ. Thus the

.TC file is no longer required to build programs defined by a project. The information stored in the . TC file includes

You might need only one copy of the. TC file

on your

hard disk. When kept with the BC.EXE file, the

TCCONFIG. TC file Is loaded, unless there is another copy in the current directory.

• editor key binding and macros

• editor mode setting (such as autoindent, use tabs, etc.)

• color tables

• 25/43 line setting

• mouse preferences

• auto-save flags

• history lists

Project files for the IDE correspond to the .CFG configuration files that you supply to the command-line compiler (the default command-line compiler configuration file is TURBOC.CFG). The

PRJCFG utility can convert .PRJ files to .CFG files and .CFG files to .PRJ files. See Chapter 7, page 189 for more information.

Loading project files You can load project files in any of three ways:

1. When invoking Borland C++, give the project name with the

.PRJ extension after the

command; for example,

BC myproj

,PRJ

You must use the ,PRJ extension in order to differentiate it from source files.

2. If there is only one .PRJ file in the current directory, the IDE assumes that this directory is dedicated to this project and automatically loads it. Thus, typing

(or

Bex) alone while the current directory contains one project file causes that project file to be loaded.

3. From within the IDE, you load a project file using the Project I

Open Project command.

Chapter

The Programmer's Platform

The project directory

When a project file is loaded from a directory other than the current directory, the current DOS directory is set to where the project is loaded from. This allows your project to be defined in terms of relative paths in the Options I Directories dialog box and also allows projects to move from one drive to another or from one directory branch to another. Note, however, that changing directories after loading a project may make the relative paths incorrect and your project unbuildable.

If this happens, change the current directory back to where the project was loaded from.

Desktop files

You can set some of these options on or off using

Options I Environment I

Desktop.

Each project file has an associated desktop file

(prjname.DSK).

This file contains state information about the associated project. While none of the information it contains is needed to build the project, all of the information is directly related to the project. The desktop file includes

• the context information for each file in the project (that is, the position in the file, the location of the window on the screen, and so on)

• the history lists for various input boxes (for example, search strings, file masks, and so on)

• layout of the windows on the desktop

• the contents of the Clipboard

• watch expressions

• breakpoints

Changing project files

Because each project file has its own desktop file, changing to another project file causes the newly loaded project's desktop to be used. Thus changing from one existing project to another existing project can change your entire window layout. When you create a new project (by using Project I Open Project and typing in a new .PRJ file), the new project's desktop inherits the previous desktop. When you select Project I Close Project, the default project is loaded and you get the default desktop and project settings.

Default files When no project file is loaded, there are two default files that serve as global place holders for project- and state-related information: TCDEF.DPR and TCDEF.DSK files, collectively referred to as the default project.

22 Bor/and

C++ User's Guide

These files are usually stored in the same directory as BC.EXE, and are created if they are not found. When you run the IDE from a directory without loading a project file, you get the desktop and settings from these files. These files are updated when you change any project-related options (for example, compiler options) or when your desktop changes (for example, the window layout).

Chapter 7, The Programmer's Platform

Borland

C++

User's Guide

H A p

T E R

Menus and options reference

This chapter provides a reference to each menu item and dialog box. It is arranged in the order that the menus appear on the screen. For information on starting and exiting the IDE, using the

IDE command-line options, and general information on how the

IDE works, see Chapter 1. Here is a high-level summary of the menus:

Chapter

Menus and options reference

I

About •••

Cl ear desktop

Repaint desktop

File Edit Search

Transfer items

Run

I

Run Ctrl-F9

Program reset Ctrl-F2

Go to cursor

Trace into

Step over

Arguments •••

Compil e Debug Proj ect Options

I

Compiler

Transfer •••

Make •••

Linker •••

Appl i cati on •••

Debugger •••

Di rectori es •••

Open ...

New

Save

Save as •••

Save all

Change dir ...

Get info ...

DOS shell

Quit

Alt-X

Compi 1 e to OBJ C:MYFILLOBJ

Make EXE file C:MYFILL EXE

Link EXE file

Build all

Remove messages

Environment

Save •••

Preferences •••

Editor ...

Mouse •••

Desktop ...

Window Help

~ r--

Code generation ...

Entry/Exit Code ...

C++ options ...

Optimi zati ons •••

Source •••

Messages •••

Names •••

Undo

Redo

Alt-Bsp

Cut

Copy

Paste

Copy examgle

Show clip oard

Shift-Del

Ctrl-Ins

Shi ft-Ins

Clear Ctrl-Del

I

Inspect... Al t-F4

Evaluate/Modify ••• Ctrl-F4

Call stack ...

Watches

Ctrl-F3

Toggle breakpoint Ctrl-F8

Breakpoi nts •••

Add watch •••

Delete watch

Edit watch ...

Remove all watches

Ctrl-F7

Size/Move

Zoom

Tile

Cascade

I

Ctrl-F5

Alt-F3

Message

Output

Watch

User screen Alt-F5

Project

Project notes

List Alt-O

Find ...

Replace ...

Search again

Go to 1 i ne number ...

Previ ous error Alt-F7

Next error

Locate function

Alt-F8

Open proj ect •••

Close project

Add item ...

Delete item

Local options ...

Include files ...

Contents

Index

Topi c search

Previ ous topi c

Help on help

Shift-Fl

Ctrl-Fl

Alt-Fl

- (System) menu

The :: menu appears on the far left of the menu bar.

Aft-Spacebar

is the fastest way to get there. When you pull down this menu, you see several general system-wide commands (About, Clear

Borland

C++

User's Guide

I About

Desktop, Repaint Desktop) and the names of programs you've installed with the Options I Transfer command.

About

The first command in the menu is About. When you choose this command, a dialog box appears that shows you copyright and version information for Borland c++. Press

Esc

or click OK (or press

Enter)

to close the box.

Clear Desktop

Choose:: I Clear Desktop to close all windows and clear all history lists. This command is useful when you're starting a new project.

Repaint Desktop

Choose:: I Repaint Desktop to have Borland C++ redraw the screen. You may need to do this, for example, if a memoryresident program has left stray characters on the screen, or possibly if you have screen-swapping turned off (Options I

Debug I Display swapping) and you're stepping through a program.

Transfer items

Any programs you've installed with the Transfer dialog box

(Options I Transfer) appear here. To run one of these programs, choose its name from the :: menu. To install programs that will then appear in this menu, choose Options I Transfer.

If you have more than one program installed with the same shortcut letter on this menu, the first program listed with that shortcut will be selected. You can select the second item by clicking it or by using the arrow keys to move to it and then pressing

Enter.

File menu

The File menu lets you open and create program files in Edit windows. The menu also lets you save your changes, perform other file functions, shell to DOS, and quit.

Chapter

Menus and options reference

File I Open

Open

[ffi

The File I Open command displays a file-selection dialog box for you to select a program file to open in an Edit window. Here is what the box looks like:

Figure 2.1

The Load a File dialog box

.. INTROll.C

INTR012.C

INTR013.C

INTR014.C

INTR015.C

INTR016.C

INTR017.C

The dialog box contains an input box, a file list, buttons labeled

Open, Replace, Cancel, and Help, and an information panel that describes the selected file. Now you can do any of these actions:

• Type in a full file name and choose Replace or Open. Open loads the file into a new Edit window.

Edit window must be active if you choose Replace; the contents of the window is replaced with the selected file.

• Type in a file name with wildcards, which filters the file list to match your specifications.

• Press J, to choose a file specification from a history list of file specifications you've entered earlier.

• View the contents of different directories by selecting a directory name in the file list.

The input box lets you enter a file name explicitly or lets you enter a file name with standard DOS wildcards (* and

?) to filter the names appearing in the history list box. If you enter the entire name and press

Enter,

Borland C++ opens it. (If you enter a file name that Borland C++ can't find, it automatically creates and opens a new file with that name.)

If you press J, when the cursor is blinking in the input box, a history list drops down below the box. This list displays the last eight file names you've entered. Choose a name from the list by

Borland

C++

User's Guide

File I Open

If you choose Replace instead of Open, the selected file replaces the file in the active Edit window instead of opening up

new window.

double-clicking it or selecting it with the arrow keys and pressing

Enter.

Once you've typed in or selected the file you want, choose the

Open button (choose Cancel if you change your mind). You can also just press

Enter

once the file is selected, or you can doubleclick the file name.

Using the File list box

You can also type

lowercase letter to search for

file name and an uppercase letter to search for

directory name.

The File list box displays all file names in the current directory that match the specifications in the input box, displays the parent directory, and displays all subdirectories. Click the list box or press

Tab

until the list box name is highlighted. You can now press

J, or

i

to select a file name, and then press

Enter

to open it.

You can also double-click any file name in the box to open it. You might have to scroll the box to see all the names. If you have more than one pane of names, you can also use

~ and

The file information panel at the bottom of the Load a File dialog box displays path name, file name, date, time, and size of the file you've selected in the list box. (None of the items on this panel are selectable.) As you scroll through the list box, the panel is updated for each file.

New

The File I New command lets you open a new Edit window with the default name NONAMExx.C (the xx stands for a number from

00 to 99). These NONAME files are used as a temporary edit buffer; Borland c++ prompts you to name a NONAME file when you save it.

Save

[ill

The File I Save command saves the file in the active Edit window to disk. (This menu item is disabled if there's no active Edit window.) If the file has a default name (NONAMEOO.C, or the like), Borland C++ opens the Save Editor File dialog box to let you rename and save it in a different directory or on a different drive.

This dialog box is identical to the one opened for the Save As command, described next.

Chapter

Menus and options reference

File I Save As

Save As

The File I Save As command lets you save the file in the active

Edit window under a different name, in a different directory, or on a different drive. When you choose this command, you see the

Save File As dialog box:

Figure 2.2

The Save File As dialog box

~ INTROll.C

INTR012.C

INTR013.C

INTR014.C

INTR015.C

INTR016.C

INTR017.C

Enter the new name, optionally with drive and directory, and click or choose

OK.

All windows containing this file are updated with the new name.

Save All

The File I Save All command works just like the Save command except that it saves the contents of all modified files, not just the file in the active Edit window. This command is disabled if no

Edit windows are open.

Change Dir

The File I Change Dir command lets you specify a drive and a directory to make current. The current directory is the one

Borland c++ uses to save files and to look for files. (When using relative paths in Options I Directories, they are relative to this current directory only.)

Here is what the Change Directory dialog box looks like:

Borland

C++

User's Guide

File I Change Dir

Figure 2.3

The Change Directory dialog box

There are two ways to change directories:

• Type in the path of the new directory in the input box and press

Enter,

Choose the directory you want in the Directory tree (if you're using the keyboard, press

Enter

to make it the current directory), then choose OK or press

Esc

to exit the dialog box.

If you choose the OK button, your changes will be made and the dialog box put away. If you choose the Chdir button, the

Directory Tree list box changes to the selected directory and displays the subdirectories of the currently highlighted directory

(pressing

Enter

or double-clicking on that entry gives you the same result). If you change your mind about the directory you've picked and you want to go back to the previous one

(and

you've yet to exit the dialog box), choose the Revert button.

Print

The File I Print command lets you print the contents of the active

Edit, Output, or Message window. Borland C++ expands tabs

(replaces tab characters with the appropriate number of spaces) and then sends it to the DOS print handler. This command is disabled if the active window cannot be printed. Use

Ctrl-K P

to print selected text only.

Get Info

The File I Get Info command displays a box with information on the current file.

Chapter

Menus and options reference

File I

Get

Info

Figure 2.4

The Get Info box

The information here is for display only; you can't change any of the settings in this box. The following table tells you what each line in the Get Info box means and where you can go to change the settings if you want to:

Table 2.1

Get Info settings

After reviewing the information in this box, press

Enter to put the box away.

Setting

Meaning

Current directory

Current file

Extended memory in use

Expanded memory in use

Lines compiled

Total warnings

Total errors

Total time

Program loaded

Program exit code

Available memory

Last step time

The default directory.

File in the active window.

Amount of extended memory reserved by

Borland

C++i

displays 0 when the IDE is in protected mode.

Amount of expanded memory reserved by

Borland C++.

Number of lines compiled.

Number of warnings issued.

Number of errors generated.

Amount of time your program has run

(debugger only).

Debugging status.

DOS termination code of last terminated program.

Amount of free DOS (640K) memory. In protected mode, this value is the number of bytes of extended memory.

Amount of time spent in last debug step.

DOS Shell

The File I DOS Shell command lets you temporarily exit Borland c++ to enter a DOS command or program. To return to Borland

C++, type

EXIT and press

Enter.

You may find that when you're debugging, there's not enough memory to execute this command. If that's the case, terminate the debug session by choosing

Run

I Program Reset

(Ctrl-F2).

Bor/and

c++

User's Guide

File I DOS Shell

Edit menu

. . Don't install any TSR programs (like SideKick) while you've shelled to DOS, because memory may get misallocated.

Note:

In dual monitor mode, the DOS command line appears on the Borland C++ screen rather than the User Screen. This allows you to switch to DOS without disturbing the output of your program. Since your program output is available on one monitor in the system, Window I User Screen and

Alt-F5

are disabled.

You can also use the transfer items on the :: (System) menu to quickly switch to another program without leaving Borland C++.

Quit

[][][KJ

The File I Quit command exits Borland C++, removes it from memory, and returns you to the DOS command line. If you have made any changes that you haven't saved, Borland C++ asks you if you want to save them before exiting.

The Edit menu lets you cut, copy, and paste text in Edit windows.

If you make mistakes, you can undo changes, and even reverse the effect of your most recent undo. You can also open a

Clipboard window to view or edit its contents, and copy text from the Message and Output windows.

Before you can use most of the commands on this menu, you need to know about selecting text (because most editor actions apply to selected text). Selecting text means highlighting it. You can select text either with keyboard commands or with a mouse; the principle is the same even though the actions are different.

From the keyboard you can use any of these methods:

• Press

Shift

while pressing any arrow key.

• To select text from the keyboard, press

Ctrl-K B

to mark the start of the block. Then move the cursor to the end of the text and press

Ctrl-K

K.

• To select a single word, move the cursor to the word and press

Ctrl-KT.

• To select an entire line, press

Ctrl-K L.

Chapter

Menus and options reference

Edit

.... With a mouse:

• To select text with a mouse, drag the mouse pointer over the desired text. If you need to continue the selection past a window's edge, just drag off the side and the window will automatically scroll.

• To select a single line, double-click anywhere in the line.

• To select text line-by-line, click-drag over the text (that is, click once and then quickly press the mouse button again and begin to drag).

• To extend or reduce the selection, Shift-click anywhere in the document (that is, hold

Shift

and clIck).

Once you have selected text, the commands in the Edit menu become available, and the Clipboard becomes useful.

The Clipboard is the magic behind cutting and pasting. It's a special window in Borland C++ that holds text that you have cut or copied, so you can paste it elsewhere. The Clipboard works in close concert with the commands in the Edit menu.

Here's an explanation of each command in the Edit menu.

Undo

Backspace

I The Edit I Undo command restores the file in the current window to the way it was before the most-recent edit or cursor movement.

There are restrictions on what operations can be undone. Undo will insert any characters that have been deleted, delete any characters that have been inserted, replace any characters that have been overwritten, and move the cursor back to a prior position.

If you delete large blocks, you may lose your Undo information.

Undoing a block operation restores the block markers to the value they had prior to the operation. Undo will not change any flag option setting that has a global effect. For example, if you use the

Ins

key to change from Insert to Overwrite mode, then choose

Undo, you won't change back into Insert mode. However, if you delete a character, switch to Overwrite mode, then choose Undo, the character you just deleted will be inserted. The effect of the operation that you performed (deleting a character) is undone regardless of the mode setting.

Changing global editing options may make Undo act differently than you expect. For instance, if you press

Tab,

then change the

Borland

C++

User's Guide

Edit I

Undo

value of Tab Width in the Editor Options dialog box, then choose

Undo, the cursor will move to the old tab location (based on certain values in the Undo buffer). As soon as you start typing, however, the cursor will move to the new tab location.

The Group Undo option in the Editor Options dialog box

(Options I Environment I Editor) affects Undo and Redo. See page

93 for information on Group Undo.

Redo

The Edit I Redo command reverses the effect of the most recent

Undo command. The Redo command only has an effect immediately after an Undo command or after another Redo command. A series of Redo commands reverses the effects of a series of Undo commands.

The Edit I Cut command removes the selected text from your document and places the text in the Clipboard. You can then paste that text into any other document (or somewhere else in the same document) by choosing Paste. The text remains selected in the Clipboard so that you can paste the same text many times.

The Edit I Copy command leaves the selected text intact but places an exact copy of it in the Clipboard. You can then paste that text into any other document by choosing Paste. You can also copy text from a Help window: With the keyboard, use

Shift

and the arrow keys; with the mouse, click and drag the text you want to copy. If the Output or Message window is the active window when you select Edit I Copy, the entire contents of the window buffer (including any nonvisible portion) get copied to the

Clipboard.

Paste

Shift

1lli!J

The Edit I Paste command inserts text from the Clipboard into the current window at the cursor position. The text that is actually pasted is the currently marked block in the Clipboard window.

You cannot paste to either the Output or Message window.

Chapter

Menus and options reference

Edit I Copy Example

Copy Example

The Edit I Copy Example command copies the preselected example text in the current Help window to the Clipboard. The examples are already predefined as pastable blocks, so you don't need to bother with marking the example you want.

Show Clipboard

The Edit I Show Clipboard command opens the Clipboard window, which stores the text you cut and copy from other windows. The text that's currently selected (highlighted) is the text Borland C++ uses when you choose Paste.

You can think of the Clipboard window as a history list of your cuts and copies. And you can edit the Clipboard so that the text you paste is precisely the text you want. Borland C++ uses whatever text is selected in the Clipboard when you choose Paste.

Normally the Clipboard contents are saved across sessions, although you can control that using Options I

Environment I Desktop.

The Clipboard window is just like other Edit windows; you can move it, resize it, and scroll and edit its contents. The only difference you'll find in the Clipboard window is when you choose to cut or copy text. When you select text in the Clipboard window and choose Cut or Copy, the selected text immediately appears at the bottom of the window. (Remember, any text that you cut or copy is appended to the end of the Clipboard-so you can paste it later.)

Clear

@@@ill

The Edit I Clear command removes the selected text but does not put it into the Clipboard. This means you cannot paste the text as you could if you had chosen Cut or Copy. The cleared text is not retrievable. You can clear the Clipboard itself by selecting all the text in the Clipboard, then selecting Edit I Clear.

Search menu

The Search menu lets you search for text, function declarations, and error locations in your files.

Borland

C++

User's Guide

Search I Find

Find

~[]][£J The Search I

Find

command displays the Find dialog box, which lets you type in the text you want to search for and set options that affect the search.

(Ctrl-Q F

is another shortcut for this command.)

Figure 2.5

The Find dialog box

I[X]

Case sensitive!

I []

Whole words OnlY!

The Find dialog box contains several buttons and check boxes:

Check the Case Sensitive box if you do want Borland C++ to differentiate uppercase from lowercase.

Check the Whole Words Only box if you want Borland C++ to search for words only (that is, the string must have punctuation or space characters on both sides).

I[]

Regular expreSSion!

Check the Regular Expression box if you want Borland C++ to recognize GREP-like wildcards in the search string. The wildcards are

$, .,

+, [], and \. Here's what they mean:

A circumflex at the start of the string matches the start of a line.

A dollar sign at the end of the expression matches the end of a line.

A period matches any character.

A character followed by an asterisk matches any number of occurrences (including zero) of that character. For example,

bo* matches bot, b, boo, and also be.

A character followed by a plus sign matches any number of occurrences (but not zero) of that character. For example,

bo+ matches bot and boo, but not be or b.

Chapter

Menus and options reference

Search I Find

[] Characters in brackets match anyone character that appears in the brackets but no others. For example

[botl

matches

0, or

t.

[A ]

A circumflex at the start of the string in brackets means

not.

Hence,

[Abotl

matches any characters except

b,

0, or

t.

[ - ] A hyphen within the brackets signifies a range of characters. For example,

[b-ol

matches any character from

b

througho.

\ A backslash before a wildcard character tells Borland C++ to treat that character literally, not as a wildcard. For example, \

A matches

A and does not look for the start of a line.

Enter the string in the input box and choose OK to begin the search, or choose Cancel to forget it.

If you want to enter a string that you searched for previously, pr~ss

J, to show a history list to· choose from.

You can also pick up the word that your cursor is currently on in the Edit window tClnd use it in the Find box by simply invoking

Find from the Search menu. You can take additional characters from the text by pressing

-7 .

Direction

(e)

Forward

( ) Backward

Choose from the Direction radio buttons to decide which direction you want Borland C++ to search-starting from the origin (which you can set with the Origin radio buttons).

Scope

(e)

Global

( ) Selected text

Choose from the Scope buttons to determine how much of the file to search in. You can search the entire file (Global) or only the selected text.

Ori9in

(e)

From Cursor

( ) Entire Scope

Choose from the Origin buttons to determine where the search begins. When Entire Scope is chosen, the Direction radio buttons determine whether the search starts at the beginning or the end of the scope. You choose the range of scope you want with the Scope radio buttons.

Replace

The Search I Replace command displays a dialog box that lets you type in the text you want to search for and text you want to replace it with.

Borland

C++ User's Guide

Search I Replace

Figure 2.6

The Replace dialog box

The Replace dialog box contains several radio buttons and check boxes-many of which are identical to the Find dialog box, discussed previously. An additional checkbox, Prompt on

Replace, controls whether you're prompted for each change.

Enter the search string and the replacement string in the input boxes and choose OK or Change All to begin the search, or choose

Cancel to forget it. If you want to enter a string you used previously, press.!. to show a history list to choose from.

If Borland C++ finds the specified text, it asks you if you want to make the replacement. If you choose OK, it will find and replace only the first instance of the search item. If you choose Change

All, it replaces all occurrences found, as defined by Direction,

Scope, and Origin.

As with the Find dialog box, you can pick up the word your cursor is currently on in the Edit window and use it in the Text to

Find input box by simply invoking Find or Replace from the

Search menu. And you can add more text from the Edit window by pressing

Search Again

@!illcg The Search I Search Again command repeats the last Find or

Replace command. All settings you made in the last dialog box used (Find or Replace) remain in effect when you choose Search

Again.

Go to Line

Number

The Search I Go to Line Number command prompts you for the line number you want to find.

Chapter

Menus and options reference

Search I Go to Line Number

Figure 2.7

The Go to Une Number dialog box

Here is what the dialog box looks like:

Borland C++ displays the current line number and column number in the lower left comer of every Edit window.

Previous Error

[]DUD

The Search I Previous Error command moves the cursor to the location of the previous error or warning message. This command is available only if there are messages in the Message window that have associated line numbers. These messages are generated by compile and transfer commands that use a Capture messages filter.

Next Error

[]DmJ

The Search I Next Error command moves the cursor to the location of the next error or warning message. This command is available only if there are messages in the Message window that have associated line numbers. These messages are generated by compile and transfer commands that use a Capture messages filter.

Locate Function

The Search I Locate Function command displays a dialog box for you to enter the name of a function to search for. This command is available only during a debugging session.

Figure 2.8

The Locate Function dialog box

Enter the name of a function or press J,. to choose a name from the history list. As opposed to the

Find

command, this command finds the declaration of the function, not instances of its use.

Bor/and

c++

User's Guide

Search I Locate Function

Run menu

The

Run

menu's commands run your program, and also start and end debugging sessions.

Run

@!illffi]

If you want to have all

Borland

C++

S features available, keep Source

Debugging set to On.

The

Run I Run

command runs your program, using any arguments you pass to it with the

Run I

Arguments command. If the source code has been modified since the last compilation, it will also invoke the Project Manager to recompile and link your program. (The Project Manager is a program building tool incorporated into the IDE; see Chapter 4, "Managing multi-file projects," for more on this feature.)

If you don't want to debug your program, you can compile and link it with the Source Debugging radio button set to None

(which makes your program compile and link faster) or to

Standalone (which gives the program more room to run) in the

Options I Debugger dialog box. If you compile your program with this check box set to On, the resulting executable code will contain debugging information that will affect the behavior of the

Run I

Run

command in the following ways:

Source code the same

If you have not modified your source code since the last compilation,

• the

Run I Run

command causes your program to run to the next breakpoint, or to the end if no breakpoints have been set.

Source code modified If you have modified your source code since the last compilation,

• and if you're already stepping through your program using the

Run I

Step Over or

Run I

Trace Into commands,

Run I Run

prompts you whether you want to rebuild your program:

• If you answer yes, the Project Manager recompiles and links your program, and sets it to run from the beginning .

• If you answer no, your program runs to the next breakpoint or to the end if no breakpoints are set.

EI and if you are not in an active debugging session, the Project

Manager recompiles your program and sets it to run from the beginning.

Chapter

Menus and options reference

RunlRun

Windows

Pressing

Glrl-Break

causes Borland C++ to stop execution on the next source line in your program. If Borland C++ is unable to find a source line, a second

Glrl-Break

will terminate the program and return you to the IDE.

You can't run or debug Windows applications within the IDE. If you try to do so, you'll get an error dialog box to that effect.

Program Reset

@!illCill

The Run I Program Reset command stops the current debugging session, releases memory your program has allocated, and closes any open files that your program was using. Use this command when you're debugging and there's not enough memory to run transfer programs or invoke a DOS shell.

Go to Cursor

The Run I Go to Cursor command runs your program from the run bar (the highlighted bar in your code) to the line the cursor is on in the current Edit window. If the cursor is at a line that does not contain an executable statement, the command displays a warning. Run

Go to Cursor can also initiate a debug session.

Go to Cursor does not set a permanent breakpoint, but it does allow the program to stop at a permanent breakpoint if it encounters one before the line the cursor is on. If this occurs, you must choose the Go to Cursor command again.

Use Go to Cursor to advance the run bar to the part of your program you want to debug.

If you want your program to stop at a certain statement every time it reaches that point, set a breakpoint on that line.

Note that if you position the cursor on a line of code that is not executed, your program will run to the next breakpoint or the end if no breakpoints are encountered. You can always use

Glrl-Break

to stop a running program.

Trace Into

[ill

The Run

Trace Into command runs your program statement-bystatement. When it reaches a function call, it executes each statement within the function, instead of executing the function as a single step (see Run

Step Over).

If a statement contains no calls

Borland C++ User's Guide

Run I Trace Into to functions accessible to the debugger, Trace Into stops at the next executable statement.

Use the Trace Into command to move the run position into a function called by the function you are now debugging. See the next section for an illustration of the differences between the

Trace Into and Step Over commands.

If the statement contains a call to a function accessible to the debugger, Trace Into halts at the beginning of the function's definition. Subsequent Trace Into or Step Over commands run the statements in the function's definition. When the debugger leaves the function, it resumes evaluating the statement that contains the call; for example, if (funcl() && func2()) do_something () ;

With the run bar on the if statement, F7will trace into func1; when on the return in func1,

will trace into func2.

will step over func2 and stop on

do-something.

Note: The Trace Into command recognizes only functions defined in a source file compiled with two options set on:

• In the Code Generation dialog box (Options I Compiler), the

Debug Info in OBJs check box must be checked .

• The Source Debugging radio buttons must be set to On (in the

Options I Debugger dialog box).

Step Over rn:J

The Run I Step Over command executes the next statement in the current function. It does not trace into calls to lower-level functions, even if they are accessible to the debugger.

Use Step Over to run the function you are now debugging, one statement at a time without branching off into other functions.

Here is an example of the difference between Run I Trace Into and

Run I Step Over. These are the first 12 lines of a program loaded into an Edit window: int findit (void)

{ return(2);

1*

Line 1

*1

Chapter

Menus and options reference

Run I Step Over

void main (void)

{ int i, j;

Line 6 */ i = findit(); /* Line 10 */ printf("%d\n", i); /* Line 11 */ j

0; . . . /* Line 12 */

findit

is a user-defined function in a module that has been compiled with debugging information. Suppose the run bar is on line 10 of your program. To position the run bar on line 10, place the cursor on line 10 and either press

or select Run I Go to

Cursor .

• If you now choose Run I Trace Into, the run bar will move to the first line of the

findit

function (line 1 of your program), allowing you to step through the function .

• If you choose Run

Step Over, the find it function will execute and the return value will be assigned to

i.

Then the run bar will move to line 11.

If the run bar had been on line 11 of your program, it would have made no difference which command you chose; Run I Trace Into and Run I Step Over both would have executed the

printf

function and moved the run bar to line 12. This is because the

printf

function does not contain debug information.

Arguments

The Run

Arguments command allows you to give your running programs command-line arguments exactly as if you had typed them on the DOS command line. DOS redirection commands will be ignored.

When you choose this command, a dialog box appears with a single input box.

Figure 2.9

The Arguments dialog box

You only need to enter the arguments here, not the program name.

Arguments take affect only when your program is started.

If you are already debugging and wish to change the arguments, then you can select Program Reset to start the program with the new arguments.

Borland C++ User's Guide

Run I Arguments

Compile menu

Use the commands on the Compile menu to compile the program in the active window or to make or build your project. To use the

Compile, Make, Build, and

Link

commands, you must have a file open in an

active

Edit window or a project defined (for Make,

Build, and Link). For example, if you open a Message or Watch window, those selections will be disabled.

Compile to OBJ

[][][ffi

The Compile I Compile to

OBI

command compiles the active editor file (a .C or .CPP file to an

.OBI

file). The menu always displays the name of the file to be created; for example,

IcomPile to OBJ c: EXAMPLE.OBJ I

When Borland C++ is compiling, a status box pops up to display the compilation progress and results. When compiling/linking is complete, press any key to remove this box. If any errors or warnings occurred, the Message window becomes active and displays and highlights the first error.

Make EXE File

[ffi

The Compile I Make EXE File command invokes the Project

Manager to make an .EXE file. The menu always displays the name of the .EXE file to be created; for example,

IMake EXE File c: EXAMPLE. EXE

For more information on the

Project Manager, see

Chapter

"Managing multi-file projects. "

The .EXE file name listed is derived from one of two names in the following order:

• the project file (.PRJ) specified with the Project I Open Project command

• the name of the file in the active Edit window (if no project is defined, you'll get the default project defined by the file

TCDEF.DPR)

Compile I Make EXE File rebuilds only the files that aren't current.

Chapter

Menus and options reference

Compile I Link EXE File

Link EXE File

The Compile I Link EXE File command takes the current

.OBI

and

.LIB files (either the defaults or those defined in the current project file) and links them without doing a make; this produces a new .EXE file.

Build All

The Compile I Build All command rebuilds all the files in your project regardless of whether they're out of date.

This command is similar to Compile I Make EXE File except that it is unconditional. It performs the following steps:

1. It deletes the appropriate precompiled header (.SYM) file, if it exists.

2. It deletes any cached auto dependency information in the project.

3. It sets the date and time of all the project's

.OBI

files to zero

4. Finally, it does a make.

If you abort a Build All command by pressing

Glr/-Break

or get errors that stop the build, you can pick up where it left off simply by choosing Compile I Make EXE File.

Remove

Messages

The Compile I Remove Messages command removes all messages from the Message window.

Debug menu

Windows

The commands on the Debug menu control all the features of the jntegrated debugger. You can change default settings for these commands in the Options I Debugger dialog box.

You can't run or debug Windows applications within the IDE. If you try to do so, you'll get an error dialog box to that effect. You must run them under Microsoft Windows and use Turbo

Debugger for Windows.

Borland C++ User's Guide

Debug I Inspect

Inspect

[][)[E]

The Debug I Inspect command opens an Inspector window that lets you examine and modify values in a data element. The type of element you're inspecting determines the type of information presented in the window. In Borland C++, you can inspect simple

(ordinal) data types like

char or unsigned long,

pointers, arrays, structures, classes, types, unions, and functions.

There are two ways to open an Inspector window:

• You can position the cursor on the data element you want to inspect, then choose

Alt-F4.

• You can also choose Debug

Inspect to bring up the Inspector dialog box, and then type in the variable or expression you want to inspect. Alternatively, you can position the cursor on an expression, select Debug

Inspect, and, while in this dialog box, press

Enter

to inspect it.

To close an Inspector window, make sure the window is active

(topmost) and press

Esc

or choose Window

Close.

Here are some additional inspection operations you can perform:

• Sub-inspecting:

Once you're in an Inspector window, you can inspect certain elements to isolate the view. When an inspector item is inspectable, the status line displays the message

Inspect." To sub-inspect an item, you move the inspect bar to the desired item and press

Enter.

Modifying inspector items:

When an inspector item can be modified, the status line displays

Alt-M Modify Field." Move the cursor to the desired item and press

AIt-M;

a dialog box will prompt you for the new value.

Range-inspect:

When you are inspecting certain elements, you can change the range of values that is displayed. For example, you can range-inspect pointer variables to tell Borland C++ how many elements the pointer points to. You can rangeinspect an inspector when the status line displays the message

"Set index range" and the command

Alt-I.

The following sections briefly describe the eight types of Inspector windows possible.

Chapter

Menus and options reference

Debug I Inspect

Ordinal Inspector windows

Ordinal Inspector windows show you the value of simple data items, such as char x

4; unsigned long y

123456L;

These Inspector windows only have a single line of information following the top line (which usually displays the address of the variable, though it may display the word "constant" or have other information in it, depending on what you're inspecting). To the left appears the type of the scalar variable

(char, unsigned long,

and so forth), and to the right appears its present value. The value can be displayed as decimal, hex, or both. It's usually displayed first in decimal, with the hex values in parentheses (using the standard C hex prefix of Ox).

If the variable being displayed is of type

char,

the character equivalent is also displayed. If the present value does not have a printing character equivalent, the backslash (\) followed by a hex value displays the character value. This character value appears before the decimal or hex values.

Pointer Inspector windows

Pointer Inspector windows show y01,l the value of data items that point to other data items, such as char *p

"abc"; int tip

0; int **ipp

&ip;

Pointer Inspector windows usually have a top line that contains the address of the pointer variable and the address being pointed to, followed by a single line of information.

To the left appears

[0], indicating the first member of an array. To the right appears the value of the item being pointed to.

If the value is a complex data item such as a structure or an array, as much of it as possible is displayed, with the values enclosed in braces ({ and n.

If the pointer is of type

char

and appears to be pointing to a nullterminated character string, more information appears, showing the value of each item in the character array. To the left in each line appears the array index ([1], [2], and so on), and the value appears to the right as it would in a scalar Inspector window. In this case, the entire string is also displayed on the top line, along

Bor/and

c++

User's Guide

Debug

I Inspect with the address of the pointer variable and the address of the string that it points to.

Array Inspector windows

Array Inspector windows show you the value of arrays of data items, such as long thread[3] [4J [5J; char message []

"eat these words";

There is a line for each member of the array. To the left on each line appears the array index of the item. To the right appears the value of the item being pointed to.

If the value is a complex data item such as a structure or array, as much of it as possible is displayed, with the values enclosed in braces ({ and

I).

Structure and union

Inspector windows

Structure and union Inspector windows show you the value of the members in your structure, class, and union data items. For example, struct date { int year; char month; char day;

} today; union { int small; long large;

} holder;

Structures and unions appear the same in Inspector windows.

These Inspector windows have as many items after the address as there are members in the structure or union. Each item shows the name of the member on the left and its value on the right, displayed in a format appropriate to its C data type.

Function Inspector windows

Function Inspector windows show the return type of the function at the bottom of the inspector. Each parameter that a function is called with appears after the memory address at the top of the list.

Function Inspector windows give you information about the calling parameters, return data type, and calling conventions for a function.

Chapter

Menus and options reference

Debug I Inspect

Class Inspector windows

The Class (or object) Inspector window lets you inspect the details of a class variable. The window displays names and values for members and methods defined by the class.

The window can be divided into two panes horizontally, with the top pane listing the data fields or members of the class, and the bottom pane listing the member function names and the function addresses. Press

Tab

to move between the two panes of the Class

Inspector window.

If the highlighted data field is a class or a pointer to a class, pressing

Enter

opens another Class Inspector window for the highlighted type. In this way, you can quickly inspect complex nested structures of classes with a minimum of keystrokes.

Constant Inspector window

Constant Inspector windows are much like Ordinal Inspector windows, but they have no address and can never be modified.

Type Inspector window

The Type Inspector window lets you examine a type. There is a

Type Inspector window for each kind of instance inspector described here. The difference between them is that instance inspectors display the

value

of a field and type inspectors display the

type

of a field.

Evaluate/Modify

@@Cill The Debug I-Evaluate/Modify command evaluates a variable or expression, displays its value, and, if appropriate, lets you modify the value. The command opens a dialog box containing three fields: the Expression field, the Result field, and the New Value field. Here is what the dialog box looks like:

Figure 2.10

The Evaluate/Modify dialog box

Borland C++ User's Guide

Debug I Evaluate/Modify

The Evaluate button is the default button; when you tab to the New Value field, the Modify button becomes the default.

The Expression field shows a default expression consisting of the word at the cursor in the Edit window. You can evaluate the default expression by pressing

Enter,

or you can edit or replace it first. You can also press

~ copying additional characters from the Edit window.

You can evaluate any valid C expression that doesn't contain

II function calls

.. symbols or macros defined with #define

• local or static variables not in the scope of the function being executed

If the debugger can evaluate the expression, it displays the value in the Result field.

If the expression refers to a variable or simple data element, you can move the cursor to the New Value field and enter an expression as the new value.

Press

Esc

to close the dialog box.

If you've changed the contents of the New Value field but do not select Modify, the debugger will ignore the New Value field when you close the dialog box.

Use a repeat expression to display the values of consecutive data elements. For example, for an array of integers named

xarray,

II xarray [0] ,5 displays five consecutive integers in decimal.

• xarray [0], 5x displays five consecutive integers in hexadecimal.

An expression used with a repeat count must represent a single data element. The debugger views the data element as the first element of an array if it isn't a pointer, or as a pointer to an array if it is.

The Debug I Evaluate/Modify command displays each type of value in an appropriate format. For example, it displays an int as an integer in base 10 (decimal), and an array as a pointer in base

16 (hexadecimal). To get a different display format, precede the expression with a comma followed by one of the format specifiers shown in Table 2.2.

Call Stack

@!ill[]IJ

The Debug I Call Stack command opens a dialog box containing the call stack. The Call Stack window shows the sequence of functions your program called to reach the function now running.

Chapter

Menus and options reference

Debug I Call Stack

At the bottom of the stack is

main;

at the top is the function that's now running.

Each entry on the stack displays the name of the function called and the values of the parameters passed to it.

Compiling with Standard

Stack Frame unchecked

I Code Generation) causes

some functions to be omitted

from the call stack. Overlays can have the same effect.

For more details, see page

66.

Initially the entry at the top of the stack is highlighted. To display the current line of any other function on the call stack, select that function's name and press

Enter.

The cursor moves to the line containing the call to the function next above it on the stack.

For example, suppose the call stack lookp.d like this: func2 () func! () main()

This tells you that

main

called

func1,

and

func1

called

func2.

If

you wanted to see the currently executing line of

func1,

you could select

func1

in the call stack and press

Enter.

The code for

func1

would appear in the Edit window, with the cursor positioned on the call to

func2.

To return to the current line of the function now being run (that is, to the run position), select the topmost function in the call stack and press

Enter.

Borland

C++

User's Guide

Table 2.2: Format specifiers recognized In debugger expressions

Character Function

H or X

Character. Shows special display characters for control characters (ASCII 0 through 31); by default, such characters are shown using the appropriate C escape sequences (\n,

\t,

and so on). Affects characters and strings.

String. Shows control characters (ASCII 0 through 31) as ASCII values using the appropriate C escape sequences. Since this is the default character and string display format, the S specifier is only useful in conjunction with the M specifier.

Decimal. Shows all integer values in decimal. Affects simple integer expressions as well as arrays and structures containing integers.

Hexadecimal. Shows all integer values in hexadecimal with the

prefix. Affects simple integer expressions as well as arrays and structures containing integers.

Floating point. Shows

significant digits

is an integer between 2 and 18). The default value is 7. Affects only floating-point values.

Memory dump. Displays a memory dump, starting with the address of the indicated expression. The expression must be a construct that would be valid on the left side of an assignment statement, i.e., a construct that denotes a memory address; otherwise, the M specifier is ignored.

By default, each byte of the variable is shown as two hex digits. Adding a

D specifier with the M causes the bytes to be displayed in decimal. Adding an

H or X specifier causes the bytes to be displayed in hex. An S or a C specifier causes the variable to be displayed as a string (with or without special characters). The default number of bytes displayed corresponds to the size of the variable, but a repeat count can be used to specify an exact number of bytes.

Pointer. Displays pointers in

seg:ofs

format with additional information about the address pointed to, rather than the default hardware-oriented

seg:ofs

format. Specifically, it tells you the region of memory in which the segment is located, and the name of the variable at the offset address, if appropriate. The memory regions are as follows:

Memory region

OOOO:OOOO-OOOO:03FF

OOOO:0400-0000:04FF

OOOO:0500-Borland C++

Borland C++-User Program PSP

User Program PSP

Evaluate message

Interrupt vector table

BIOS data area

M5-DOS/TSRs

Borland C++

User Process PSP

User Program-top of RAM

AOOO:OOOO-AFFF:FFFF

BOOO:OOOO-B7FF:FFFF

B800:0000-BFFF:FFFF

COOO:OOOO-EFFF:FFFF

FOOO:OOOO-FFFF:FFFF

Name of a static user variable if its address falls inside the variables allocated memory; otherwise nothing

EGA/VGA Video RAM

Monochrome Display RAM

Color Display RAM

EMS Pages/ Adaptor BIOS ROMs

BIOS ROMs

Structure/Union.

Displays field names as well as values, such as {X:l,

Y:I0,

2:5 }. Affects only structures and unions.

Chapter

Menus and options reference

Debug I Watches

Watches

The Debug I Watches command opens a pop-up menu of commands that control the use of watch expressions. Watch expressions can be saved across sessions; see Options I

Environment I Desktop. The following sections describe the commands in this pop-up menu.

Add Watch

@!ill(fl]

The Add Watch command inserts a watch expression into the

Watch window.

When you choose this command, the debugger opens a dialog box and prompts you to enter a watch expression. The default expression is the word at the cursor in the current Edit window.

There's also a history list available if you want to quickly enter an expression you've used before.

When you type a valid expression and press

Enter

or click OK, the debugger adds the expression and its current value to the Watch window.

If the Watch window is the active window, you can insert a new watch expression by pressing

Ins.

Delete Watch

The Delete Watch command deletes the current watch expression from the Watch window (which must be the active window in order to use this command). To delete a watch expression other than the current one, select the desired watch expression and press

Del

Gtrl-Y.

Edit Watch

The Edit Watch command allows you to edit the current watch expression in the Watch window. A history list is available to save you time retyping.

When you choose this command, the debugger opens a dialog box containing a copy of the current watch expression. Edit the expression and press

Enter.

The debugger replaces the original version of the expression with the edited one.

You can also edit a watch expression from inside the Watch window by selecting the expression and pressing

Enter.

Borland

C++

User's Guide

Debug I Watches I Remove All Watches

Remove All Watches

The Remove All Watches command deletes all watch expressions from the Watch window.

Toggle Breakpoint

@illCill

The Debug I Toggle Breakpoint command lets you set or clear an unconditional breakpoint on the line where the cursor is positioned. When a breakpoint is set, it is marked by a breakpoint highlight. Breakpoints can be saved across sessions using

Options I Environment I Desktop. See the following section for more information on breakpoints.

Breakpoints

Figure 2.11

The Breakpoints dialog box

The Debug I Breakpoints command opens a dialog box that lets you control the use of breakpoints-both conditional and unconditional ones. Here is what the dialog box looks like:

. = = - -

Break oints

:~. ~.\~~~

-Breakpoint List Linel Condition Pass

**4W*IWW:**

MW,.;MQMMi

iM%SkkIS:V'JSJPW·

-)IGWJ~

IImIJ lI!mmJ tBJ . . ilmmJ

- = = - - = = = = - - - = - - = = = = = = = = -

The dialog box shows you all set breakpoints, their line numbers, and the conditions. The condition has a history list so you can select a breakpoint condition that you've used before.

You can remove breakpoints from your program by choosing the

Delete button. You can also view the source where existing breakpoints are set by choosing the View button. View moves the cursor to the selected breakpoint. This command does not run your code; it only positions the cursor at active breakpoints in the

Edit window.

Choose Edit to add the new one to the list. When you edit a breakpoint, this dialog box appears over the first one:

Chapter

Menus and options reference

Debug I Breakpoints

Figure 2.12

The Breakpoint Modify/New dialog box

Again, line number and conditions are that of the breakpoints you've set. Use Pass Count to set how many times the breakpoint should be skipped before stopping. The At button lets you specify a breakpoint at a particular function (you must be debugging to access this).

This dialog box also has a New button, which lets you enter breakpoint information for a new breakpoint, and a Modify button, which accepts the settings of the box.

Your program stops wherever it encounters a breakpoint in the course of running. When the program stops, the run bar is on the line containing the breakpoint. (The breakpoint highlight is obscured by the run bar; it reappears when the run bar moves on.)

When a source file is edited, each breakpoint" sticks" to the line where it is set. Breakpoints stay set until you:

• delete the source line a breakpoint is set on

• clear a breakpoint with Toggle Breakpoint

Borland C++ will attempt to track breakpoints in two cases:

• If you edit a file containing breakpoints and then don't save the edited version of the file.

• If you edit a file containing breakpoints and then continue the current debugging session without remaking the program.

(Borland C++ displays the warning prompt "Source modified, rebuild?")

Before you compile a source file, you can set a breakpoint on any line, even a blank line or a comment. When you compile and run the file, Borland C++ validates any breakpoints that are set and gives you a chance to remove, ignore, or change invalid breakpoints. When you are debugging the file, Borland C++ knows which lines contain executable statements, and will warn you if you try to set invalid breakpoints.

Borland

C++

User's Guide

Debug I Breakpoints

You can set an unconditional breakpoint without going through the dialog box by choosing the Debug I Toggle Breakpoint command.

Project menu

If you have project files in

Turbo

C 2.0, you can convert

them to Borland C++ format using the standalone utility

PRJCNVT. See UTIL. DOC for details.

The Project menu contains all the project management commands to

• create a project

• add or delete files from your project (for examples on how to use the Project Manager, see Chapter 4, "Managing multi-file projects")

• specify which program your source file should be translated with

• set options for a file in the project

• specify which command-line override options to use for the translator program

• specify what the resulting object module is to be called, where it should be placed, whether the module is an overlay, and whether the module should contain debug information

• view included files for a specific file in the project

Open Project

The Open Project command displays the Load Project File dialog box, which allows you to select and load a project or create a new project by typing in a name.

Figure 2.13

The Project File dialog box

FI GDEMO. PRJ

LISTDEMO.PRJ

MCIRCLE.PRJ

PIXEL. PRJ

VCIRCLE.PRJ

WHELLO.PRJ

STARTUP\

Chapter

Menus and options reference

Project I Open Project

This dialog box lets you select a file rtame similar to the File I Open dialog box, discussed on page 28. The file you select will be used as a project file, which is a file that contains all the information needed to build your project's executable. Borland C++ uses the project name when it creates the .EXE and .MAP files. A typical project file has the extension .PRJ.

Close Project

Choose Project I Close Project when you want to remove your project and return to the default project (TCDEF.DPR).

Add Item

Choose Project I Add Item when you want to add a file to the project list. This brings up the Add Item to Project List dialog box:

Figure 2.14

The Add Item to Project List dialog box

This dialog box is set up much like the Load File dialog box (File I

Open). Choosing the Add button puts the currently highlighted file in the Files list into the Project window. The chosen file is added to the Project window File list immediately after the highlight bar in the Project window. The highlight bar is advanced each time a file is added. (When the Project Window is active, you can press

Ins

to add a file.)

Delete Item

Choose Project I Delete Item when you want to delete a file in the

Project window. When the Project window is active, you can press

Del

to delete a file.

Borland

c++

User's Guide

Project I Local Options

Local Options

Figure 2.15

The Override Options dialog box

The Local Options command opens the following dialog box:

These command-line options are not supported: c,

Efilename,

/pathname, L,

/x,M,Q,y.

The Override Options dialog box lets you include command-line override options for a particular project-file module. It also lets you give a specific path and name for the object file and lets you choose a translator for the module.

Any program you installed in the Transfer dialog box with the

Translator option checked appears in the list of Project File

Translators (see page 74 for information on the Transfer dialog box).

I[ ]

Overlay this module

Check the Overlay this Module option if you want the selected module or library (or project item) to be overlaid. This item is local to one file. It is disabled if the qverlay support checkbox is not marked (in Options I Compile I Code Generation).

I [ ]

Exclude debug information

Check the Exclude Debug Information option to prevent debug information included in the module you've selected from going

_ _ _ _ _ _ _ _

...J. into the .EXE.

I[]

Exclude from link

Use this switch on already debugged modules of large programs.

You can change which modules have debug information simply by checking this box and then re-linking (no compiling is required).

Check the Exclude from Link option if you don't want this module linked in.

Chapter

Menus and options reference

Project I Include Files

Include Files

Choose Project

Include Files to display the Include Files dialog box; do this when you want to see which files are included by the file you chose from the Project window. When you're in the

Project Window, you can press

Spacebar

to display the Include

Files dialog box. This command is disabled if you've yet to build a project.

The Include Files dialog box looks like this:

Figure 2.16

The Include Flies dialog box

:. \INCLUDE

After a file has been compiled, information is collected about that file (notice that the Project window has code size information). In this state, the Project manager also knows which include file the module references. You can view the active Edit window's include files in the Include Files dialog box. From the Project Manager window, press

Spacebar

to display the dialog box. From an Edit window, go to the Project menu and choose Include Files. You can scroll through the list of files displayed. The default action is to view the selected file, so pressing

Enter

opens that include file into an Edit window.

Options menu

The Options menu contains commands that let you view and change various default settings in Borland C++. Most of the commands in this menu lead to a dialog box.

Borland

C++

User's Guide

Options I Compiler

Compiler

The Options I Compiler command displays a pop-up menu that gives you several options to set that affect code compilation. The following sections describe these commands.

Code Generation The Code Generation command displays a dialog box. The settings in this box tell the compiler to prepare the object code in certain ways. The dialog box looks like this:

Figure 2.17

The Code Generation dialog box

Here are what the various buttons and check boxes mean:

Model

( ) Ti ny

(.) Small

( ) Medium

( ) Compact

( ) Large

( ) Huge

Options

[X] Treat enums as 1nts

[ ] Word alignment

[ ] Duplicate strings merged

[ ] Unsigned characters

[ ] Precompiled headers

The Model buttons determine which memory model you want to use. The memory model chosen determines the default method of memory addressing. The default memory model is Small. Refer to

Chapter 6, "Memory management," in the

Programmer's Guide

for more information about memory models in general. There are some restrictions about which memory models you can use effectively for different types of Windows executables; see page

115 in Chapter 3 for a discussion of those restrictions.

The options control various code generation defaults .

• When checked, Treat enums as ints causes the compiler to always allocate a whole word. Unchecked, this option tells the compiler to allocate an unsigned or signed byte if the minimum and maximum values of the enumeration are both within the range of 0 to 255 or -128 to 127, respectively .

• Word Alignment (when checked) tells Borland C++ to align noncharacter data (within structures and unions only) at even addresses. When this option is off (unchecked), Borland C++

Chapter

Menus and options reference

Options I Compiler I Code Generation

See Appendix

for more on precompiled headers.

Assume SS equals DS ee)

Default for memory model e )

Never

( ) Always

IDefines uses byte-aligning, where data (again, within structures and unions only) can be aligned at either odd or even addresses, depending on which is the next available address.

Word alignment increases the speed with which 80x86 processors fetch and store the data.

• Duplicate 5trings Merged (when checked) tells Borland C++ to merge two strings when one matches another. This produces smaller programs, but can introduce bugs if you modify one string.

• Unsigned Characters (when checked) tells Borland C++ to treat all

char

declarations as if they were

unsigned char

type.

• Check Precompiled Headers when you want the IDE to generate and use precompiled headers. Precompiled headers can dramatically increase compilation speeds, though they require a considerable amount of disk space. When this option is off (the default), the IDE will neither generate nor use precompiled headers. Precompiled headers are saved in

PROJECTNAME.5YM.

If the Default For Memory Model radio button is pushed, whether the stack segment (55) is assumed to be equal to the data segment

(DS) is dependent on the memory model used. Usually, the compiler assumes that 55 is equal to 05 in the small, tiny, and medium memory models (except for DLLs). 5ee pages 112 and

166 for detailed and specific explanations of what the compiler assumes for each memory model and for Windows applications and DLLs.

When the Never radio button is pushed, the compiler will not assume 55 is equal to D5.

The Always button tells the compile~ to always assume that SS is equal to DS. It causes the IDE to substitute the COFx.OBJ startup module for COx.OBJ to place the stack in the data segment.

Use the Defines input box to enter macro definitions to the preprocessor. You can separate multiple defines with semicolons

(;) and assign values with an equal sign (=); for example,

TESTCODE;PROGCONST=5

Leading and trailing spaces will be stripped, but embedded spaces are left intact.

If you want to include a semicolon in a macro, you must place a backslash (\) in front of it.

Borland

C++

User's Guide

Options I Compiler I Code Generation

Figure 2.18

The Advanced Code

Generation dialog box

The Code Generation dialog box has a button called More that takes you to the Advanced Code Generation dialog box. Here's what that dialog box looks like:

Floating Point

( ) None

(e)

Emulation

( ) 8087

( ) 80287

Instruction Set

(e)

8088/8086

( ) 80186

( ) 80286

Oetions

LX]

Generate underbars

[ ] Line numbers debug info

[X] Debug info in OBJs

[X] Fast floating point

[ ] Fast huge poi nters

[ ] Generate COMDEFs

[ ] Automatic far data

The Floating Point buttons let you decide how you want Borland

C++ to handle floating-point numbers.

• Choose None if you're not using floating point.

(If you choose

None and you use floating-point calculations in your program, you get link errors.)

Choose Emulation if you want your program to detect whether your computer has an 80x87 coprocessor (and to use it if you do).

If it is not present, your program will emulate the 80x87.

• Choose 8087 or 80287 to generate direct 8087 or 80287 inline code.

The Instruction Set radio buttons let you choose what instruction set to generate code for. The default instruction set, 8088/8086, works with all PCs.

The advanced options are shown to the left.

• When checked, the Generate Underbars option automatically adds an underbar, or underscore, character ( _ ) in front of every global identifier (that is, functions and global variables).

If you are linking with standard libraries, this box must be checked.

• Line Numbers Debug Info (when checked) includes line numbers in the object and object map files (the latter for use by a symbolic debugger). This increases the size of the object and map files but does not affect the speed of the executable program.

Since the compiler might group together common code from multiple lines of source text during jump optimization, or might reorder lines (which makes line-number tracking difficult), you might want to make sure the Jump Optimization

Chapter

Menus and options reference

Options I Compiler I Code Generation

See page

769

for more details

fast huge pointers.

This option is ignored if you're using the tiny, small, or medium memory models.

check box (Options I Compiler I Optimizations) is off

(unchecked) when this option is checked.

• Debug Info in OBJs controls whet4er debugging information is included in object (.OBD files. The default for this check box is on (checked), which you need in order to use both the integrated debugger and the standalone Turbo Debugger.

• This option allows you to link and create larger object files.

While this option doesn't affect execution speed, it

does

affect compilation time. We recommend that you have this option checked.

If you want debugging information with this option checked, turn off debug information in Options I Debugging, or, even better, link with debugging information, then use

TDSTRIP

-5 to strip it off to a separate .IDS file for debugging. IDSTRIP is documented in the online file called UTIL.DOC.

• Fast Floating Point lets you optimize floating-point operations without regard to explicit or implicit type conversions. When this option is unchecked, the compiler follows strict ANSI rules regarding floating-point conversions.

• The Fast Huge Pointers option normalizes huge pointers only when a segment wrap-around occurs in the offset portion of the segment. This greatly speeds up the computation of huge pointer expressions, but must be used with caution, as it can cause problems for huge arrays if array elements cross a segment boundary.

• When checked, the Generate COMDEFs option allows a definition of a variable to appear in header files as long as it is not initialized. Thus a definition such as int SomeArray [256]

could appear in a header file that is then included in many modules, and the compiler will generate it as a communal variable (a COMDEF record rather than a PUBDEF record). The linker will then only generate one instance of the variable so it will not be a duplicate definition linker error.

• The Automatic Far Data option and the Far Data Threshold type-in box work together. When checked, the Automatic Far

Data option tells the compiler to automatically generate far objects; the Far Data Threshold < 32767> specifies the size portion needed to complete the command. The size value is ignored if

Automatic Far Data is not checked.

Borland

C++

User's Guide

Options I Compiler I Entry/Exit Code

Entry/Exit Code

See Chapter

for more on prolog and epilog code.

When you compile a C or c++ program for Windows or DOS, the compiler needs to know which kind of prolog and epilog to create for each of a module's functions.

If the program is intended for Windows, the compiler generates a different prolog and epilog than it would for OOS. Because of this, you must use the the Entry/Exit Code Generation dialog box to set the appropriate application.

If you use the Set Application

Options dialog box (described on page 86), the settings in the

Entry /Exit Code dialog box will already be correct for the type of application you choose.

This dialog box also allows you to select the calling convention and to set a couple of stack options. All options affect what code is generated for function calls and returns.

Figure 2.19

The Entry/Exit Code dialog box

. . You can set prolog/ epilog code for DOS

or

for Windows, but not for both.

If you want to set the prolog/ epilog code for a DOS application, you need to select DOS Standard or DOS Overlay.

• Push the DOS Standard radio button to tell the compiler to generate code that may not be safe for overlays. If you don't plan to create an overlaid application, use this option.

• Push the DOS Overlay radio button to tell the compiler to generate overlay safe code. Use this option when you're creating an overlaid application.

If you want to set the prolog/ epilog code for a Windows application, you need to select one of five options.

• Windows All Functions Exportable is the most general kind of

Windows executable, although not necessarily the most efficient. It assumes that all functions are capable of being called

Chapter

Menus and options reference

Options I Compiler I Entry/Exit Code by the Windows kernel or by other modules, and generates the necessary overhead information for every function, whether the function needs it or not. The module definition file will control which functions actually get exported.

• Use Windows Explicit Functions Exported if you have functions that will not be called the Windows kernel; it isn't necessary to generate export-compatible prolog/ epilog code information for these functions. The _export keyword provides a way to tell the compiler which specific functions will be exported: Only those far functions with _export will be given the special Windows prolog/ epilog code.

• Push the Windows Smart Callbacks button to select Borland

C++ smart callbacks. See page 112 in Chapter 3 for details on smart callbacks.

The compiler must be able to assume that DS

S5 for all functions in the module. You therefore should

not

choose Smart

Callbacks for a module that will be compiled under the huge memory model.

• Push the Windows DLL All Functions Exportable button to create an .OBJ file to be linked as a .DLL with all functions exportable.

• Push the Windows DLL Explicit Functions Exported button to create an .OBJ file to be linked as a .DLL with certain functions explicitly selected to be exported. Otherwise this is essentially the same as Windows Explicit Functions Exported, see that discussion for more.

Calling Convention

~. ~ ~ascal

Important!

Stack Options

[X] Standard Stack Frame

[ ] Test Stack Overflow

The Calling Convention options cause the compiler to generate either a C calling sequence or a Pascal calling sequence for function calls. The differences between C and Pascal calling conventions are in the way each handles stack cleanup, order of parameters, case, and prefix (underbar) of global identifiers.

not change this option unless you're an expert and have read

Chapter

"Interfacing with assembly language," in the Programmer's

Guide.

• Standard Stack Frame (when checked) generates a standard stack frame (standard function entry and exit code). This is helpful when debugging-it simplifies the process of tracing back through the stack of called subroutines.

If you compile a source file with this option off (unchecked), any function that does not use local variables and has no parameters is compiled with abbreviated entry and return code.

Bor/and

c++

User's Guide

Options I Compiler I Entry/Exit Code

This makes the code shorter and faster, but prevents the

Debug I Call Stack com11land from "seeing" the function. Thus, you should always check the option when you compile a source file for debugging.

• When checked, the Test Stack Overflow generates code to check for a stack overflow at run time. Even though this costs space and time in a program, it can be a real lifesaver, since a stack overflow bug can be difficult to track down. c++ Options

The c++

Options command displays a dialog box that contains settings that tell the compiler to prepare the object code in certain ways when using c++.

Figure 2.20

The C++ options dialog box

C++ Virtual Tables ee)

Smart e )

Local e )

External e )

Publ i c

The

C++

Virtual Tables radio buttons let you control c++ virtual tables and the expansion of inline functions when debugging.

• The Smart option generates

C++ virtual tables (and inline functions not expanded inline) so that only one instance of a given virtual table or inline function will be included in the program. This produces the smallest and most efficient executables, but uses

.OBI

(and .ASM) extensions only available with TLINK 3.0 and TASM 2.0 (or newer).

• The Local option generates local virtual tables (and inline functions not expanded inline) such that each module gets its own private copy of each virtual table or inline function it uses; this option uses only standard

.OBI

(and .ASM) constructs, but produces larger executables.

• The External option generates external references to virtual tables; one or more of the modules comprising the program must be compiled with the Public option to supply the definitions for the virtual tables.

• The Public option generates public definitions for virtual tables.

Chapter

Menus and options reference

Options I Compiler I C++ Options

Use c++ Compiler

(e)

CPP extension only

( ) C++ always

The Use C++ Compiler radio buttons tell Borland C++ whether to always compile your programs as C++ code, or to always compile

·your code as C code except when the file extension is .CPP.

[Xl

Out-of-line inline functions •

[ 1

Far virtual tables

Use Out-of-Line Inline Functions when you want to step through or set breakpoints on inline functions .

• The Far Virtual Tables option causes virtual tables to be created in the code segment instead of the data segment, and makes virtual table pointers into full 32-bit pointers (the latter is done automatically if you are using the huge memory model).

(for example; a DLL and an executable using that DLL). You must compile all modules that may share objects either entirely with or entirely without this option. You can achieve the same effect by using the

huge or _export

modifiers on a class-by-class basis.

Optimizations The Optimizations command displays a dialog box. The settings in this box tell the compiler to prepare the object code in certain ways to optimize the size or speed. The dialog box looks like this:

Figure 2.21

The Optimizations Options dialog box

O~timization Options

Jump optimization

The Optimizations Options affect how optimization of your code occurs.

• Register Optimization suppresses the reloading of registers by remembering the contents of registers and reusing them as often as possible.

Exercise caution when using this option. The compiler can't detect whether a value has been modified indirectly by a pointer.

Borland

C++

User's Guide

Options I Compiler I Optimizations

Important!

None e )

Automatic

Optimize For ee) e )

Size

Speed

• Jump Optimization reduces the code size by eliminating redundant jumps and reorganizing loops and switch statements.

When this option is checked, the sequences of tracing and stepping in the debugger can be confusing, since there might be multiple lines of source code associated with a particular generated code sequence. For best stepping results, turn this option off (uncheck it) while you are debugging.

The Register Variables radio buttons suppress or enable the use of register variables.

With Automatic chosen, register variables are automatically assigned for you. With None chosen, the compiler does not use register variables even if you've used the

register

keyword. With

register

keyword and a register is available.

(See Chapter 6, "Memory management," in the

Programmer's Guide

for more details.)

Generally, you can keep this option set to Automatic unless you're interfacing with preexisting assembly code that does not support register variables.

The Optimize For buttons let you change Borland C++'s code generation strategy. Normally the compiler optimizes for size, choosing the smallest code sequence possible. You can also have the compiler optimize for speed, so that it chooses the

fastest

sequence for a given task.

If you are creating Windows applications, normally you'll want to optimize for speed.

Source

The Source command displays a dialog box. The settings in this box tell the compiler to expect certain types of source code. The dialog box looks like this:

Figure 2.22

The Source Options dialog box

Chapter

Menus and options reference

Options I Compiler I Source

Source Options

[ ] Nested corrments

Keywords

(e)

Borland C++

( ) ANSI

( ) UNIX V

( ) Kernighan and Ritchie

IIdentifier Length

321

The Nested Comments checkbox allows you to nest comments in

Borland C++ source files. Nested comments are not allowed in standard C implementations, and they are not portable.

The Keyword radio buttons tell the compiler how to recognize keywords in your programs.

• Choosing Borland C++ tells the compiler to recognize the

Borland C++ extension keywords, including near, far, huge, asm, cdecl, pascal, interrupt, _es, _export, _ds, _cs, _ss, and the register pseudovariables LAX, _BX, and so on). For a complete list, refer to Chapter 1, "Lexical grammar," in the

Pro-

grammer's Guide.

• Choosing ANSI tells the compiler to recognize only ANSI keywords and treat any Borland C++ extension keywords as normal identifiers.

• Choosing UNIX V tells the compiler to recognize only UNIX V keywords and treat any Borland C++ extension keywords as normal identifiers. iii

Choosing Kerrtighan and Ritchie tells the compiler to recognize only the K&R extension keywords and treat any Borland C++ extension keywords as normal identifiers.

Use the Identifier Length input box to specify the number

(n)

of significant characters in an identifier. Except in C++, which recognizes identifiers of unlimited length, all identifiers are treated as distinct only if their first

n

characters are distinct. This includes variables, preprocessor mac,ro names, and structure member names. The number can be from 1 to 32; the default is 32.

Messages The Messages command displays a dialog box that lets you set several options that affect compiler error messages in the IDE.

Figure 2.23

The Compiler Messages dialog box

Borland

C++

User's Guide

Options I Compiler I Messages

Errors: stop after 25

Warnings: stop after

100

[X]

Display warnings

• The Errors: Stop After option causes compilation to stop after a specified number of errors have been detected. The default is

25, but you can enter any number from 0 to 255. (Entering 0 causes compilation to continue until the end of the file.)

• The Warnings: Stop After option causes compilation to stop after a specified number of warnings have been detected. The default is 100, but you can enter any number from 0 to 255.

(Entering

0 causes compilation to continue until the end of the file or until the error limit has been reached, whichever comes first.)

• The Display Warnings option (when checked) means that any or all of the following warning types can be displayed if chosen:

Iportability···1

• Portability warnings

• ANSI violations

• C++ warnings

• Frequent errors

When this option is off (unchecked), none of these warnings will be displayed.

When you choose the Portability button in the Compiler Messages dialog box, another dialog box appears that lets you make specific settings in this category:

Figure 2.24

The Portability warnings dialog box

IANSI Violations··.1

I!!!!Pe!!~!!!!on

Non-portable pointer comparison

Constant out of range in comparison

Constant is long

Conversion may lose significant digits

Mixing pointers to signed and unsigned char

7LIEIIJ~

LlmmJ IUIl:IIJ

- - = = = = - - = - - = = = = = = = = = = =

Check the warnings you want to be notified of and uncheck the ones you don't. Choose OK to return to the Compiler Messages dialog box.

When you choose the ANSI Violations button in the Compiler

Messages dialog box, another dialog box appears that lets you make specific settings in this category. Here is what this dialog box looks like:

Chapter

Menus and options reference

Options I Compiler I Messages

Figure 2.25

The ANSI Violations dialog box ons may n rn a va ue

Both return and return of a value used

Suspicious pointer conversi on

Undefi ned structure 'i dent'

Redefinition of 'ident' is not identical

H d i l l th th di it tm1mII!I!II -+~f~

================================-

Check the warnings you want to be notified of and uncheck the ones you don't. Choose OK to return to the Compiler Messages dialog box.

When you choose the More ANSI Violations button in the ANSI

Violations dialog box, another dialog box appears with more settings you can make in this category:

Figure 2.26

The More ANSI Violations dialog box ses on

0 e

Goto bypasses initialization of a local variable

Untyped bit field assumed signed int

'ident' declared as both external and static

Declare 'ident' prior to use in prototype

Division by zero

Initializing 'ident' with 'ident'

Thi i iti li ti i

, ti

11 b k t d

-+Lll!IllJf-

===---=====--====--====--======

Check or uncheck these warnings just like in the previous dialog box's and choose OK to return to the ANSI Violations dialog box.

Ic++ warnings···1

Figure 2.27

The C++ Warnings dialog box

When you choose the C++ Warnings button in the Compiler

Messages dialog box, another dialog box appears that lets you make specific settings in this category. Here is what this dialog box looks like:

= = = = = = = = = = = = gnmen e initialization without a class name

Functions containing 'ident' are not expanded inline

Functi on 'i dent' shoul d have a prototype

'i dent' is both a structure tag and a name

Temporary used to i ni ti ali ze 'i dent'

Temporary used for parameter 'ident'

The constant member 'ident' is not initialized

This style of function definition is now obsolete

Use of 'overload' is now unnecessary and obsolete

Obso 1 ete syntax. use '::' instead

Assigning 'ident' to 'ident'

'ident' hides virtual function 'ident'

Non-const function 'i dent' called for const object

-+Lll!IllJf-

= = = = = = = = = = = = = = = = = = = = = = = = = =

Bor/and C++ User's Guide

Options I Compiler I Messages

IFrequent errors ••• I

Check the warnings you want to be notified of and uncheck the ones you don't. Choose OK to return to the Compiler Messages dialog box.

When you choose the Frequent Errors button in the Compiler

Messages dialog box, another dialog box appears that lets you make specific settings in this category. Here is what this dialog box looks like:

Figure 2.28

The Frequent Errors dialog box Unreachable code

Code has no effect

Possible use of 'ident' before definition

'ident' is assigned a value that is never used

Parameter 'i dent' is never used

P ibl i t ' t

IGlllDII!IJ -)1II!aII~ ~

- = = = = = = = - - = = = = = = = = =

Check the errors you want to be notified of and uncheck the ones you don't. Choose OK to return to the Compiler Messages dialog box.

Choosing the More button takes you to the More Frequent Errors dialog box:

Figure 2.29

The More Frequent Errors dialog box uous on dent' decl ared but never used

Ambi guous operators need parentheses

Structure passed by value

No declarati on for functi on 'i dent'

Call to function with no prototype

Restarting compile using assembly

Unknown assembler instruction

Function definition cannot be a typedef'ed declaration

Ill-formed pragma

Array vari ab 1 e 'i dent' is near

-)1II!aII~ ~

= = = = = = = = = = = = = = = - - = = = = = = =

Check or uncheck these errors like in the previous dialog boxes and choose OK to return to the Frequent Errors dialog box.

Names

The Names command brings up the following dialog box, which lets you change the default segment, group, and class names for code, data, and BSS sections.

Don't change the settings in this

command unless you are an expert and have read Chapter 6, UMemory

management," in the Programmer's Guide.

Chapter

Menus and options reference

Options I Compiler I Names

Figure 2.30

The Segment Names dialog box

-"111.-.. -

The asterisk means that the default names will be used if no other names are specified. See page

777

for the default names.

Transfer

The Options I Transfer command lets you add or delete programs in the :: menu. Once you've done so, you can run those programs without actually leaving Borland C++. You return to Borland C++ after you exit the program you transferred to. The Transfer command displays this dialog box:

Figure 2.31

The Transfer dialog box

The Transfer dialog box has two sections:

• the Program Titles list

• the Transfer buttons

The Program Titles section lists short descriptions of programs that have been installed and are ready to execute. You might need to scroll the list box to see all the programs available.

The Transfer buttons let you edit and delete the names of programs you can transfer to, as well as cancel any changes you've made to the transfer list. There's also a Help button to get more information about using the transfer dialog box. Here's a rundown of the buttons.

Borland

C++

User's Guide

Options I Transfer

The Edit button

Choose Edit to add or change the Program Titles list that appears in the :: menu. The Edit button displays the Modify/New Transfer Item dialog box.

If you're positioned on a transfer item when you select Edit, the input boxes in the Modify/New dialog box are automatically filled in; otherwise they're blank.

Figure 2.32

The Modify/New Transfer

Item dialog box

Using the Modify/New dialog box, you take these steps to add a new file to the Transfer dialog box:

For a full description

of these

powerful macros, see the following section, "Transfer macros."

This step is optional.

Type a short description of the program you're adding on the

Program Title input box. (Note that when using a translator in a project, it must match the transfer title exactly.)

Note that if you want your program to have a keyboard shortcut (like the 5 in the Save command or the

in the Cut command), you should include a tilde ( .... ) in the name. Whatever character follows the tilde appears in bold or in a special color in the :: menu, indicating that you can press that key to choose the program from the menu.

2. Tab to Program Path and enter the program name and optionally include the full path to the program. (If you don't enter an explicit path, only programs in the current directory or programs in your regular DOS path will be found.)

3. Tab to Command Line and type any parameters or macro commands you want passed to the program. Macro commands always start with a dollar sign ($) and are entered in uppercase. For example, if you enter

$CAP EDIT, all output from the program will be redirected to a special Edit window in Borland C++.

4. If you want to assign a hot key, tab to the Hot Key options and assign a shortcut to this program. Transfer shortcuts must be

Chapter

Menus and options reference

Options I Transfer

Shift

plus a function key. Keystrokes already assigned appear in the list but are unavailable.

5. Now click or choose the New button to add this program to the list.

To modify an existing transfer program, cursor to it in the

Program Titles list of the Transfer dialog box and then choose

Edit. After making the changes in the Modify/New Transfer dialog box, choose the Modify button.

I[ ]

Translator

The Translator check box lets you put the Transfer program into the Project File Translators list (the list you see when you choose

Project

Local Options). Check this option when you add a transfer program that is used to build part of your project.

The Delete button

The Delete button removes the currently selected program from the list and the :: menu.

Transfer macros The IDE recognizes certain strings of characters called

transfer macros

in the parameter string of the Modify/New Transfer Item dialog box. There are three kinds of macros: state, file name, and instruction.

State macros

are expanded according to the state of the IDE. The state macros are

The transfer macros are listed alphabetically and described in more detail starting on page 77.

$COL

$CONFIG

$DEF

$ERRCOL

$ERRLINE

$ERRNAME

$INC

$LIB

$LINE

$PRJNAME

File name macros

are actually functions that take file names as arguments and return various parts of the file name. They allow you to build up new file name specifications from existing file names. For example, you can pass TDUMP a macro like this:

$DIR($EXENAME) $ NAME ($EDNAME) .OBJ

This macro gives you the output directory path, the file name only in the active Edit window, and an explicit extension. If your current directory is C: \ WORK, your output directory is TEST, and the active editor contains MYPROG.C, then TDUMP receives the parameter c:\WORK\TEST\MYPROG.OBJ

Borland

C++

User's Guide

Options I Transfer

The file name macros are

$DIR

$DRIVEO

$EDNAME

$EXENAME

$EXTO

$NAMEO

$OUTNAME

You can use any program that has line-oriented messages output (file and line number) with this macro.

Instruction macros

tell the IDE to perform some action or make some setting. The instruction macros are

$CAP EDIT

$CAP MSGifilter)

$DEPO

$IMPLIB

$MEM(kb to reserve)

$NOSWAP

$PROMPT

$RC

$SA VE ALL

$SA VB CUR

$SA VB PROMPT

$TASM

$CAP EDIT:

This macro tells the IDE to redirect program output into a standard file. After the transfer program is completed, a new editor window is created, and the captured output is displayed. The captured output resides in a special Edit window titled Transfer Output.

For $CAP EDIT to work correctly, the transfer program must write to DOS standard output.

$CAP MSG(filter):

Captures program output into the Message window, using filter as a DOS filter for converting program output into Message window format.

We've provided four filters for this macro: GREP2MSG.EXE for

GREP, IMPL2MSG.EXE for IMPLIB, RC2MSG.EXE for the

Resource Compiler, and TASM2MSG.EXE for Turbo Assembler

(TASM). We've included the source code for these filters so you can write your own filters for other transfer programs you install.

$COl:

Column number of current editor.

If the active window is not an editor, then the string is set to O.

$CONFIG:

Complete file name of the current configuration file.

This is a null string if no configuration file is defined. This macro is intended for use by programs that access or modify the configuration file. Besides providing the name of the file, this macro causes the current configuration to be saved (if modified) and reloaded when control returns to the IDE.

Chapter

Menus and options reference

Options I Transfer

TEML is

Pascal-like language that has many built-in primitive editor commands. Its use is documented online.

Use this macro with the Turbo Editor Macro Language (TEML) compiler. With it, you can edit the TEML script file in an editor and then invoke the Turbo Editor Macro Compiler (TEMC) to process the script. When the configuration file is reloaded, your new or modified editor commands will be in effect. When installing TEMC as a transfer item, use the following command line:

This macro is only used by the project manager.

$EDNAME $CONFIG

This assumes the current Edit window contains the TEML script file to be processed.

$DEF:

Pulls in the contents of the Options I Compiler I Code

Generation "Defines" type-in box. Use this macro to specify define directives to an external translator.

$DEP():

This macro provides the ability to automatically rebuild resources as part of a project make if one of the resource components has been modified. For example, let's say your Windows resource MYAPP1.RES for your application MYAPP1.EXE consists of the following files:

• MYAPP1.RC (the resource source file)

• MYAPP1.H (the header file for MYAPP1.EXE)

• MYAPP1.ICO (the icon for MYAPP1.EXE, included in

MYAPP1.RC)

• MYAPP1.BMP (the bitmap used with MYAPP1.EXE, included in MYAPP1.RC)

To ensure that MYAPP1.RES gets recompiled any time you update one of the components, you'd add the following dependencies to the Options field in the Project

Local Options dialog box for MYAPP1.RC: .

$DEP(MYAPP1.H MYAPP1.ICO MYAPP1.BMP)

When you choose Compile I Make, the project manager scans for the $DEP macro and verifies that all explicit dependencies given are older than the resulting MYAPP1.RES file. If one or more aren't, the project manager recompiles MYAPP1.RC.

You can give explicit dependencies to any makeable project item.

Just place the files you want the source to be dependent on in parentheses, separated by blanks, commas, or semicolons. If autodependency checking is on, explicit dependencies are checked after any auto dependencies.

Bor/and

c++

User's Guide

Options I Transfer

$DIR():

Directory of the file argument, full path.

$DRIVE():

Drive of the file argument, in the form

D:.

$EDNAME:

Complete file name of file in active editor. This is a null string if the active window is not an editor.

$ERRCOL:

Column number of current error in file $ERRNAME.

If there are no messages, then string is expanded to null string.

$ERRLINE:

Line number of current error in file $ERRNAME. If there are no messages, then string is expanded to null string.

$ERRNAME:

Complete file name of file referred to by the selected messages in the Message window. This is a null string if there are no messages or the currently selected message does not refer to a file.

$EXENAME:

Program's file name (including output path), based on the project name or, if there is no project defined, then the name of the .EXE that would be produced from the active editor window. If the Windows DLL Linker option is selected, the file's extension will be .DLL.

$EXT():

Extension of the file argument; this includes the dot (for example, .CPP).

$IMPLlB:

Executes IMPLIB.This macro expands to

$NOSWAP $CAP MSG(IMPL2MSG)

$DRIVE($EXENAME) $DIR($EXENAME) $ NAME ($EXENAME) .LIB $EXENAMEldef_name

If the Use DLL File Exports radio button is pushed (Options

MAKE

Generate Import Library), $EXENAME is part of the expansion. If the Use DEF file Exports radio button is pushed, the name of the DEF file in the project (represented by

del_name)

is used.

$INC:

Pulls in the contents of the Options I Directories I Include

Directories type-in box.

$LlB:

Pulls in the contents of the

Op~ions

I Directories I Library

Directories type-in box.

$LlNE:

Line number of current editor.

If the active window is not an editor, then the string is set to

o.

$MEM(Kb

to reserve):

This macro tells the IDE how much memory to try to give the transfer program. The IDE gives up as much memory as possible, to either the amount specified or the

Chapter

Menus and options reference

Options I Transfer

80 maximum available, whichever is smaller. You'll get an error if no memory is specified.

$NAME():

Name part of the file argument; does not include the dot.

$NOSWAP:

This macro tells the IDE not to swap to the User

Screen when running the program. It pops up a box that indicates which transfer program is running. Use this macro in conjunction with$CAP.

$OUTNAME:

This macro expands to the path and file name that appear in the Project I Local Options Output Path type-in box (in the active edit window). For example, if the project contains

STARS.C, the default Output Path type-in is STARS.OB}. So if

STARS.C is in the active edit window, $OUTNAME expands to

STARS.OB}. If you've edited the type-in box so it says ..

\MOON. XYZ,

$OUTNAME will expand to .. \MOON.XYZ. This macro is useful when you are specifying modules for your user-defined translators. For example, you could define a TLIB translator and set the command line to

TLIB MYLIB +$OUTNAME which adds the object module of the file in the active edit window to the library MYLIB.

$PRJNAME:

The current project file. Null string if no project is defined.

$PROMPT:

This macro tells the IDE to display the expanded parameter string before calling the transfer program. The command line that will be passed is displayed in a dialog box.

This allows you to change or add to the string before it is passed.The position of $PROMPT command in the command line determines what is shown in the dialog prompt box. You can place constant parameters in the command line by placing them before $PROMPT. For example, the

/ c

$PROMPT dir is constant and doesn't show in the dialog box, but

dir

can be edited before the command is run.

$RC:

This macro is predefined for use with the Resource

Compiler. Since the Resource Compiler can be invoked for two separate reasons, $RC is expanded differently depending on whether you are compiling a .RC file into a .RES file or binding the .RES file to an executable file.

Borland

C++

User's Guide

Options I Transfer

In any case, in order to change the behavior of the Resource

Compiler

• when compiling an .RC file, change the command line in

Project I Local Options for the .RC file in the Project Manager

• when binding a .RES file to an .EXE or a DLL, change the options in Options I Transfer I Resource Compiler

If you are compiling

a

.Re file into

a

.RES file,

$RC is expanded like this:

$SAVE CUR $NOSWAP $CAP MSG(RC2MSG) -R -I$INC -FO $OUTNAME $EDNAME

If you are binding

a .RES to an .EXE file,

$RC is expanded like this:

$NOSWAP $CAP MSG(RC2MSG) res_name $EXENAME

The variable

res_name

is defined as one of the following, in this order:

1. If there is a file in the project with a .RES extension,

res_name

will be that file.

If there is no file with a .RES extension, and there

is

a file with a .RC extension,

res_name

is the name given by $OUTNAME for the .RC file.

If neither of the above apply (implying there are no resources),

res_name

is blank.

$SAVE ALL:

This macro tells the IDE to save all modified files in all Edit windows that have been modified, without prompting.

$SAVE CUR:

This macro tells the IDE to save the file in the current editor if it has been modified. This ensures that the invoked program will use the latest version of the source file.

$SAVE PROMPT:

This macro tells the IDE to prompt when there are unsaved files in editor windows. You will be asked if you want to save any unsaved files.

$TASM:

This macro is predefined for use with Turbo Assembler.

It uses the TASM2MSG filter to trap TASM messages.

$TASM

is essentially shorthand for this:

$NOSWAP $SAVE CUR $CAP MSG(TASM2MSG) $EDNAME,$OUTNAME

WRITEMSG(filename):

This macro copies the contents of the

Message window to the specified ASCII file. The translator can

Chapter

Menus and options reference

Options I Transfer

parse the file and act on the messages so desired. For example,

WRITEMSG(C: \MESSAGES.TXT) writes to the file

MESSAGES. TXT on your root directory.

Running DOS commands

If you want to run DOS commands from within the integrated environment, you can set up a simple transfer macro that will let you do so. Just add this transfer item: command

$MEM(128) $PROMPT

When you invoke this transfer item, a dialog box appears and prompts you for DOS input. Since the $PROMPT command appears later in the string, the text

command

/c won't show up in the dialog's input box. This lets you just type dir, chkdsk, del

. ,

or whatever DOS command you want to run.

Transfer memory settings

Different programs have different memory needs. For example,

GREP can run in very little memory, where many popular editors require 200-300K to work well.

If you use the

$MEM()

macro, you can specify (on a program-byprogram basis) how much memory the IDE should give to the transfer programs. The less memory you devote to a transfer program, the quicker the transfer to and from the program occurs.

There may be some cases where the IDE cannot give up as much memory as you requested. When this happens, the IDE gives up as much as it can. There are certain states in the IDE that require more memory than others; for example, while debugging a program, the IDE will tie up more resources than when not debugging. Use Program Reset

(Ctrl-F2)

to free up debugging memory.

In those cases where you want the IDE to give up all its memory, give it a large number, like 640K. How much memory is actually given up is dependent on how much you have when you start

Borland C++.

Make

The Options I Make command displays a dialog box that lets you set conditions for project management. Here's what the dialog box looks like:

Borland

C++

User's Guide

Options I Make

Figure 2.33

The Make dialog box

Break Make On e }

Warnings ee}

Errors e }

Fatal errors e }

Link

~. ~ ~~e

DLL fi 1 e exports

() Use DEF fi 1 e exports

Use the Break Make On radio buttons to set the condition that will stop the making of a project. The default is to stop after compiling a file with errors.

The Generate Import Library buttons control when and how

IMPLIB is executed during the MAKE process. The Use DLL File

Exports option generates an import library that consists of the exports in the DLL. The Use DEF File Exports generates an import library of exports in the DEF file.

If either of these options is checked, MAKE invokes IMPLIB after the linker has created the

DLL. This option controls how the transfer macro $IMPLIB gets expanded.

[X] Check Auto-dependenci es

When the Check Auto-dependencies option is checked, the Project

Manager automatically checks dependencies for every

.OBI

file on disk that has a corresponding.C source file in the project list.

The Project Manager opens the

.OBI

file and looks for information about files included in the source code. This information is always placed in the

.OBI

file by both Borland C++ and the commandline version of Borland C++ when the source module is compiled.

Then every file that was used to build the .OBJ file is checked for time and date against the time and date information in the

.OBI

file. The source file is recompiled if the dates are different. This is called an

autodependency check.

If this option is off (unchecked), no such file checking is done.

See the $DEPO transfer macro on page 78.

After the C source file is successfully compiled, the project file contains valid dependency infromation for that file. Once that valid information is in the project file, the Project Manager does the autodependency check using that information. This is much faster than reading each

.OBI

file.

Chapter

Menus and options reference

Options I Linker

Linker

The Options I Linker command lets you make several settings that affect linking. The Linker command opens this dialog box:

Figure 2.34

The Unker dialog box

This dialog box has several check boxes and radio buttons. The following sections contain short descriptions of what each does.

Ma!~lF6~~

Segments

Publics

() Detai 1 ed

Standard DOS

( Overlaid DOS

( Windows

EXE

( ) Wi ndows DLL

EXE

Use the Map File radio buttons to choose the type of map file to be produced. For settings other than Off, the map file is placed in the output directory defined in the Options

Directories dialog box.

The default setting for the map file is Off.

Use these radio buttons to set your application type. Standard

DOS EXE produces a normal executable that runs under DOS.

Overlaid DOS EXE produces an executable that is capable of being overlaid. Windows EXE produces a Windows application, while Windows DLL produces a Windows dynamic link library.

I []

Initialize segments

I

If checked, Initialize Segments tells the linker to initialize uninitialized segments. (This is normally not needed and will make your .EXE files larger.)

I [ ]

Defaul t 11 brari es

When you're linking with modules created by a compiler other than Borland C++, the other compiler may have placed a list of default libraries in the object file.

I[X] Graphics libraryl

If the Default Libraries option is checked, the linker tries to find any undefined routines in these libraries as well as in the default libraries supplied by Borland C++. If this option is off

(unchecked), the linker searches only the default libraries supplied by Borland C++ and ignores any defaults in .OB} files.

The Graphics Library option controls the automatic searching of the BGI graphics library. When this option is checked (the

Borland C++ User's Guide

Options I Linker

default), it's possible to build and run single-file graphics programs without using a project file. Unchecking this option speeds up the link step a bit because the linker doesn't have to search in the BGI graphics library file.

Note:

You can uncheck this option and still build programs that use BGI graphics, provided you add the name of the BGI graphics library (GRAPHICS. LIB) to your project list.

I[X]

Warn duplicate symbols

The Warn Duplicate Symbols option affects whether the linker warns you of previously encountered symbols in

.LIB files.

I []

"No stack" warning

The "No Stack" Warning option affects whether the linker generates the "No stack" message. It's normal for a program generated under the tiny model to display this message if the message is not turned off.

I[X]

Case-sensitive Linkl

The Case-Sensitive Link option affects whether the linker is casesensitive. Normally, this option should be checked, since C and

C++ are both case-sensitive languages.

I [ ]

Case-sensitive exports

I

By default, the linker ignores case with the names in the

IMPORTS and EXPORTS sections of the module definition file. If you want the linker be case-sensitive in regard to these names, check this option. This option is probably only useful when you are trying to export non-callback functions from DLLs-as in exported C++ member functions. This option isn't necessary for normal Windows callback functions (declared FAR PASCAL).

I[]

Pack code segments

This option applies only to Windows applications and DLLs.

When this option is checked, the linker tries to minimize the number of code segments by packing multiple code segments together; typically, this will improve performance. This option will never create segments greater than 64K.

Code Pack Size 8192

Segment Alignment 512

You can change the default code packing size to anything between 1 and 65,536 with Code Pack Size. See page 247 for a more in-depth discussion of desirable sizes.

With Segment Alignment, you can set the segment alignment.

Note that the alignment factor will be automatically rounded up to the nearest power of two (meaning that if you enter 650, it will be rounded up to 1,024). The possible numbers you can enter must fall in the range of 2 to 65,535.

Chapter

Menus and options reference

Options I Application

The Set

Application

Options dialog box

This dialog box provides the easiest and safest way to set up compilation and linking for a DOS or Windows executable. To use this dialog box, simply push one of the buttons. Borland C++ will verify and, if necessary, changes some of the settings in the Code

Generation, Entry/Exit Code Generation, and Linker dialog boxes. See page 65 (Entry/Exit Code) for detailed information on the code generated. Use this dialog box for initial setup only.

Figure 2.35

Set Application Options

The standard options for applications and libraries each accomplish a set of tasks. You can choose only one button at a time. The current settings fields are updated when you press the button.

DOS Standard:

• pushes the Small memory model radio button in the Code

Generation dialog box

• unchecks Assume SS not equal DS in the Code Generation dialog box

• pushes the DOS Standard radio button in the Entry/Exit Code

Generation dialog box

• pushes the Standard DOS .EXE radio button in the Linker dialog box

• checks the Graphics Library option in the Linker dialog box

DOS Overlay:

• pushes the Medium memory model button in the Code

Generation dialog box

• unchecks Assume SS not equal DS in the Code Generation dialog box

Bor/and

c++

User's Guide

Options I Application

• pushes the DOS Overlay button in the Entry/Exit Code

Generation dialog box

• pushes the Overlaid DOS .EXE button in the Linker dialog box

• checks the Graphics Library option in the Linker dialog box

Windows App:

• pushes the Small memory model button in the Code Generation dialog box

• unchecks Assume SS not equal DS in the Code Generation dialog box

• pushes the Windows All Functions Exportable button in the

Entry /Exlt Code Generation dialog box

II pushes the Windows .EXE button in the Linker dialog box

• unchecks the Graphics Library option in the Linker dialog box

Windows DLL:

.. pushes the Compact memory model button in the Code

Generation dialog box

• checks Assume SS not equal DS in the Code Generation dialog box

• pushes the Windows DLL All Functions Exportable button in the Entry/Exit Code Generation dialog box

• unchecks the Graphics Library option in the Linker dialog box

Debugger

The Options I Debugger command lets you make several settings affecting the integrated debugger. This command opens this dialog box:

Figure 2.36

The Debugger dialog box

The following sections describe the contents of this box.

Chapter

Menus and options reference

Options I Debugger

Source Debugging ee)

On e )

Standalone e )

None

Display Swapping e )

None ee)

Smart e )

Always

Note

The Source Debugging radio buttons determine whether debugging information is included in the executable file and how the .EXE is run under Borland C++.

Programs linked with this option set to On (the default) can be debugged with either the integrated

~ebugger or the standalone

Turbo Debugger. Switch this back to On when you want to debug in the IDE.

If you set this option to Standalone, programs can be debugged only with Turbo Debugger, although they can still be run in

Borland C++.

If you set this option to None, programs cannot be debugged with either debugger, because no debugging information has been placed in the .EXE file.

The Display Swapping radio buttons let you set when the integrated debugger will change display windows while running a program.

If you set Display Swapping to None, the debugger does not swap the screen at all. You should only use this setting for debugging sections of code that you're certain do not output to the screen.

When you run your program in debug mode with the default setting of Smart, the debugger looks at the code being executed to see whether it will generate output to the screen. If the code does output to the screen (or if it calls a function), the screen is swapped from the IDE screen to the User Screen long enough for output to be displayed, then is swapped back. Otherwise, no swapping occurs.

Be aware of the following with smart swapping:

• It swaps on any function call, even if the function does no screen output.

• In some situations, the IDE screen might be modified without being swapped; for example, if a timer interrupt routine writes to the screen.

If you set Display Swapping to Always, the debugger swaps screens every time a statement executes. You should choose this setting any time the IDE screen is likely to be overwritten by your running program.

If you're debugging in dual monitor mode (that is, you used the

Borland C++ command-line

option), you can see your

88 Bor/and

C++ User's Guide

Options I Debugger

Inspectors

[XJ Show inherited

[X] Show methods

( ) Show decimal

( ) Show hex ee)

Show both

Program Heap Size

64 Kbytes

Usually, it's only meaningful to increase heap size when working with large data models.

program's output on one monitor and the Borland C++ screen on the other. In this case, Borland C++ never swaps screens and the

Display Swapping setting has no effect.

In the Inspectors checkboxes, when Show Inherited is checked, it tells the integrated debugger to display all member functions and methods-whether they are defined within the inspected class or inherited from a base class. When this option is not checked, only those fields defined in the type of the inspected object are displayed.

When checked, the Show Methods option tells the integrated debugger to display member functions when you inspect a class.

Check the Show Decimal, Show Hex, or Show Both radio buttons when you want to control how the values in inspectors are displayed. Show both is on by default.

You can use the Program Heap Size input box to input how much memory Borland C++ should assign a program when you debug it. The actual amount of memory that Borland C++ tries to give to the program is equal to the size of the executable image plus the amount you specify here.

The default value for the program heap size is 64 Kbytes. You may want to increase this value if your program uses dynamically allocated objects.

Directories

The Options I Directories command lets you tell Borland C++ where to find the files it needs to compile, link, and output binary and map files. This command opens the following dialog box containing three input boxes:

Figure 2.37

The Directories dialog box

Here is what each input box is for:

• The Include Directories input box specifies the directory that contains your include files. Standard include files are those

Chapter

Menus and options reference

Options I Directories

given in angle brackets

«» in an

#include

statement (for example,

#include

<myfile.h». These directories are also searched for quoted Includes not found in the current directory.

Multiple directory names are allowed, separated by semicolons.

• The Library Directories input box specifies the directories that contain your Borland C++ startup object files (CO?OBJ) and run-time library files (.LIB files) and any other libraries that your project may use. Multiple directory names are allowed, separated by semicolons.

• The Output Directory input box specifies the directory that stores your .OBJ, .EXE, and .MAP files. Borland C++ looks for that directory when doing a make or run, and to check dates and times of .0BJs and .EXEs. If the entry is blank, the files are stored in the current directory.

Use the following guidelines when entering directories in these input boxes:

• You must separate multiple directory path names (if allowed) with a semicolon (;). You can use up to a maximum of 127 characters (including whitespace).

• Whitespace before and after the semicolon is allowed but not required.

• Relative and absolute path names are allowed, including path names relative to the logged position in drives other than the current one. For example,

C:\C\LIB;C:\C\MYLIBS;A:\BORLANDC\MATHLIBS;A: .. \VIDLIBS

Environment

The Options I Environment command lets you make environment-wide settings. This command opens a menu that lets you choose settings from Preferences, Editor, Mouse, and Desktop.

Preferences Here's what the Preferences dialog box looks like:

90 Bor/and

C++

User's Guide

Options I Environment I Preferences

Figure 2.38

The Preferences dialog box

Screen Size

(e) 25 1 i nes

( ) 43/50 lines

The Screen Size radio buttons let you specify whether your IDE screen is displayed in 25 lines or 43/50 lines. One or both of these buttons will be available, depending on the type of video adapter in your PC.

When set to 25 lines (the default), Borland C++ uses 25 lines and

80 columns. This is the only screen size available to systems with a monochrome display or Color Graphics Adapter (CGA).

If your PC has EGA or VGA, you can set this option to 43/50 lines. The IDE is displayed in 43 lines by 80 columns if you have an EGA, or 50 lines by 80 columns if you have a VGA.

Source Tracking

( ) New window

(e) Current window

Auto Save

[ ] Editor Fil es

[X] Envi ronment

[X] Desktop

[X] Project

When stepping source or viewing the source from the Message window, the IDE opens a new window whenever it encounters a file that is not already loaded. Selecting Current Window causes the IDE to replace the contents of the topmost Edit window with the new file instead of opening a new Edit window.

If Editor Files is checked in the Auto Save options, and if the file has been modified since the last time you saved it, Borland C++ automatically saves the source file in the Edit window whenever you choose the Run

Run (or any debug/run command) or File

DOS Shell command.

When the Environment option is checked, all the settings you made in this dialog box will be saved automatically when you exit

Borland C++.

When Desktop is checked, Borland C++ controls whether your desktop is saved on exit and whether it's restored when you return to Borland C++.

When the Project option is checked, Borland C++ saves all your project, auto-dependency, and module settings on exit and restores them when you return to Borland C++.

Chapter

Menus and options reference

Options I Environment I Preferences

[ ] Save Old Messages

When Save Old Messages is checked, Borland C++ saves the error messages currently in the Message window, appending any messages from further compiles to the window. When a file is compiled, any messages for that file are removed from the

Message window and new messages are added to the end.

Messages are not saved from one session to the next. When you uncheck this box, Borland C++ automatically clears messages before a compile, a make, or a transfer that uses the Message window.

Editor Opti ons

[X] Create backup files

[X] Insert mode

[X] Autoindent mode

X] Use tab character

X Optimal fill

Backspace unindents

[Xl Cursor through tabs

[ Group undo

[X Persisten blocks

Editor

If you choose Editor from the Environment menu, these are the options you can pick from:

• When Create Backup Files is checked (the default), Borland

C++ automatically creates a backup of the source file in the Edit window when you choose File I Save and gives the backup file the extension .BAK.

• When Insert Mode is not checked, any text you type into Edit windows overwrites existing text. When the option is checked, text you type is inserted (pushed to the right). Pressing

Ins

toggles Insert mode when you're working in an Edit window.

• When Autoindent Mode is checked, pressing

Enter

in an Edit window positions the cursor under the first nonblank character in the preceding nonblank line. This can be a great aid in keeping your program code more readable.

• When Use Tab Character is checked, Borland C++ inserts a true tab character (ASCII 9) when you press

Tab.

When this option is not checked, Borland C++ replaces tabs with spaces.

If there are any lines with characters on them prior to the current line, the cursor is positioned at the first corresponding column of characters following the next whitespace found. If there is no

"next" whitespace, the cursor is positioned at the end of the line. After the end of the line, each

Tab

press is determined by the Tab Size setting.

• When you check Optimal Fill, Borland C++ begins every autoindented line with the minimum number of characters possible, using tabs and spaces as necessary. This produces lines with fewer characters than when Optimal Fill is not checked.

• When Backspace Unindents is checked (which is the default) and the cursor is on a blank line or the first non-blank character

Borland

C++

User's Guide

Options I Environment I Editor

of a line, the

Backspace

key aligns (outdents) the line to the previous indentation level.

• When you check Cursor Through Tabs, the arrow keys will move the cursor to the middle of tabs; otherwise the cursor jumps several columns when cursoring over a tab.

• When Group Undo is unchecked, choosing Edit I Undo reverses the effect of a single editor command or keystroke. For example, if you type

ABC, it will take three Undo commands to delete C, then B, thenA.

If Group Undo is checked, Undo reverses the effects of the previous command and all immediately preceding commands of the same type. The types of commands that are grouped are insertions, deletions, overwrites, and cursor movements. For example, if you type ABC, one Undo command deletes ABC.

For the purpose of grouping, inserting a carriage return is considered an insertion followed by a cursor movement. For example, if you press

Enter,

then type ABC, choosing Undo once will delete the ABC, and choosing Undo again will move the cursor to the new carriage return. Choosing Edit I Redo at that point would move the cursor to the following line. Another

Redo would insert ABC. (See page 34 for more information about Undo and Redo.)

• When this option is checked (the default), marked blocks behave as they always have in Borland's C and C++ products.

With this option unchecked, marked blocks behave differently in these instances:

1. Pressing the

Del

key or the

Backspace

key clears the entire selected text.

2. Inserting text (pressing a character, pasting from clipboard) replaces the entire selected text with the inserted text.

3. Moving the cursor out of the block de-selects the text.

ITab Size

81

If you check Use Tab Character in this dialog box and press

Tab,

Borland C++ inserts a tab character in the file and the cursor moves to the next tab stop. The Tab Size input box allows you to dictate how many characters to move for each tab stop. Legal values are 2 through 16; the default is 8.

To change the way tabs are displayed in a file, just change the tab size value to the size you prefer. Borland C++ redisplays all tabs

Chapter

Menus and options reference

Options I Environment I Editor

IDefault Extension CPP I in that file in the size you chose. You can save this new tab size in your configuration file by choosing Options I Save Options.

The Default Extension input box lets you tell Borland C++ which extension to use as the default when compiling and loading your source code. Changing this extension doesn't affect the history lists in the current desktop.

Mouse

When you choose Mouse from the Environment menu, the Mouse

Options dialog box is displayed, which contains all the settings for your mouse. These are the options available to you:

Right Mouse Button

( ) Nothing

Topic search

Go to cursor

Breakpoint

( ) Inspect

( ) Evaluate

( ) Add watch

The Right Mouse Button radio buttons determine the effect of pressing the right button of the mouse (or the left button, if the reverse mouse buttons option is checked). Topic Search is the default.

Here's a list of what the right button would do if you choose something other than Nothing:

Topic Search

Go to Cursor

Breakpoint

Inspect

Evaluate

Add Watch

Same as Help I Topic Search

Same as Run

Go To Cursor

Same as Debug I Toggle Breakpoint

Same as Debug

Inspect

Same as Debug I Evaluate

Same as Debug

Watches

Add Watch

Mouse Double Click

___

Test Slow

.·m~l!!1.tIm-

In the Mouse Double Click box, you can change the slider control bar to adjust the double-click speed of your mouse by using the arrow keys.

Moving the scroll box closer to Fast means Borland C++ requires a shorter time between clicks to recognize a double click. Moving the scroll box closer to Slow means Borland C++ will still recognize a double click even if you wait longer between clicks.

If you want to experiment with different settings, you can double-click the Test button above the scroll bar. When you successfully double-click the bar it becomes highlighted.

[] Reverse Mouse Buttons I

When Reverse Mouse Buttons is checked, the active button on your mouse is the rightmost one instead of the leftmost. Note, however, that the buttons won't actually be switched until you choose the OK button.

Depending on how you hold your mouse and whether you're right- or left-handed, the right mouse button might be more comfortable to use than the left.

Borland

C++

User's Guide

Options I Environment I Desktop

Desktop

Desktop Preferences

[X] History lists

[X] Cl i pboard

[ ] Watch expressions

[ ] Breakpoi nts

The Desktop dialog box lets you set whether history lists, the contents of the Clipboard, watch expressions, and breakpoints are saved across sessions. History lists and the contents of the

Clipboard are saved by default; because watch expressions and breakpoints may not be meaningful across sessions, they are not saved by default. You can change these defaults by unchecking or checking the respective options.

Save

The Options I Save command brings up a dialog box that lets you save settings that you've made in both the Find and Replace dialog boxes (off the Search menu) and in the Options menu

(which includes all the dialog boxes that are part of those commands) for IDE, Desktop, and Project items. Options are stored in three files, which represent each of these categories.

If it doesn't find the files, Borland C++ looks in the Executable directory (from which BC.EXE or BCX.EXE is run) for the same file.

Window menu

The Window menu contains window management commands.

Most of the windows you open from this menu have all the standard window elements like scroll bars, a close box, and zoom boxes. Refer to page 13 for information on these elements and how to use them.

At the bottom of the Window menu, the Window I List command appears. Choose this command for a list of all open windows as well as recently closed ones. (A recently closed window appears with

closed

before it; choose it to reopen it.)

Size/Move

@!Oem

Choose Window I Size/Move to change the size or position of the active window.

When you choose this command, the active window moves in response to the arrow keys. When the window is where you want it, press

Enter.

You can also move a window by dragging its title bar.

Chapter

Menus and options reference

Window I Size/Move

If you press

Shift

while you use the arrow keys, you can change the size of the window. When it's the size you want it, press

Enter.

If a window has a resize comer, you can drag that comer or any other comer to resize it.

Zoom

Choose Window I Zoom to resize the active window to the maximum size. If the window is already zoomed to the max, you can choose this command again to restore it to its previous size.

You can also double-click anywhere on the top line (except where an icon appears) of a window to zoom or unzoom it.

Tile

Choose Window I Tile to tile all your open windows.

Cascade

Choose Window I Cascade to stack all open windows.

[ill

Choose Window I Next to make the next window active, which makes it the topmost open window.

Close

@J[0

Choose Window I Close to close the active window. You can also click the close box in the upper left comer to close a window.

Message

Choose Window I Message to open the Message window and make it active. The Message window displays error and warning messages, which you can use for reference, or you can select them and have the corresponding location be highlighted in the Edit window. When a message refers to a file that is not currently loaded, you can press the

Spacebar

to load that file. You can also display transfer program output in this window.

When an error is selected in the Message window, press

Enter

to show the location of the error in the Edit window and make the

Edit window active at the point of error.

Borland C++ User's Guide

Window I Output

To close the window, click its close box or choose Window I Close.

Output

Choose Window

Output to open the Output window and make it active. The Output window displays text from any DOS command-line text and any text generated from your program (no graphics).

The Output window is handy while debugging because you can view your source code, variables, and output all at once. This is especially useful when you've set the Options I Environment dialog box to a 43/50 line display and you are running a standard

25-line mode program. In that case, you can see almost all of the program output and still have plenty of lines to view your source code and variables.

If you would rather see your program's text on the full screen-or if your program generates graphics-choose the Window I User

Screen command instead.

To close the window, click its close box or choose Window I Close.

Watch

Choose Window

Watch to open the Watch window and make it active. The Watch window displays expressions and their changing values so you can keep an eye on how your program evaluates key values.

You use the commands in the Debug

Watches pop-up menu to add or remove watches from this window. Refer to the section on this menu for information on how to use the Watch window (page

54).

To close the window, click its close box or choose Window I Close.

User Screen

Choose Window I User Screen to view your program's full-screen output. If you would rather see your program output in a Borland

C++ window, choose the Window I Output command instead.

Clicking or pressing any key returns you to the IDE.

Chapter

Menus and options reference

Window I Register

Register

Choose Window I Register to open the Register window and make it active.

The Register window displays CPU registers and is used when debugginginline ASM and TASM modules in your project.

To close the window, click its close box or choose Window I Close.

Project

Choose Window I Project to open the Project window, which lets you view files that you're using to create your program.

Project Notes

Choose Window I Project Notes to write down any details, make to-do lists, or list any other information about your project files.

List

Choose Window I List to get a list of all the windows you've opened. The list contains the names of all files that are currently open as well as any of the last eight files you've opened in an Edit window but have since closed. A recently closed file appears in the list prefixed with the word

closed.

When you choose an already open file from the list, Borland C++ brings the window to the front and makes it active. When you choose a closed file from the list, Borland C++ reopens the file in an Edit window the same size and location as when the window was closed. The cursor is positioned at its last location.

Press

Alt-O

to pop up a complete list of all open windows and all

Edit windows you've closed. For a full rundown of how to manage windows, see page 15.

Help menu

The Help menu gives you access to online help in a special window. There is help information on virtually all aspects of the

Borland

C++ User's Guide

Window I List

IDE and Borland c++.

(Also, one-line menu and dialog box hints appear on the status line whenever you select a command.)

To open the Help window, do one of these actions:

When getting help in a dialog box or menu, you cannot resize the window or copy to the clipboard. In this instance, Tab takes you to dialog box controls, not the next keyword.

• Press

at any time (including from any dialog box or when any menu command is selected) .

• When an Edit window is active and the cursor is positioned on a word, press

Ctrl-F1

to get language help. a Click Help whenever it appears on the status line or in a dialog box.

To close the Help window, press

Esc,

click the close box, or choose

Window I Close. You can keep the Help window onscreen while you work in another window unless you opened the Help window from a dialog box or pressed

when a menu command was selected.

(If you press

or click on another window while you're in Help, the Help window remains onscreen.)

Help screens often contain

keywords

(highlighted text) that you can choose to get more information. Press

Tab

to move to any keyword; press

Enter

to get more detailed help. (As an alternative, move the cursor to the highlighted keyword and press

Enter.

With a mouse, you can double-click any keyword to open the help text for that item.

You can also cursor around the Help screen and press

Ctrl-F1

any

word to get help.

If the word is not found, an incremental search is done in the index and the closest match displayed.

When the Help window is active, you can copy from the window and paste that text into an Edit window. You do this just the same as you would in an Edit window: Select the text first (using

Shift~ ,

Left arrow, Up arrow, Down arrow), choose Edit I Copy, move to an Edit window, then choose Edit I Paste.

To select text in the Help window, drag across the desired text or, when positioned at the start of the block, press

Shift~,~,

I,

J, to mark a block.

You can also copy preselected program examples from help screens by choosing the Edit I Copy Example command.

Chapter

Menus and options reference

Help I Contents

The Help I Contents command opens the Help window with the main table of contents displayed. From this window, you can branch to any other part of the help system.

You can get help on Help by pressing

when the Help window is active. You can also reach this screen by clicking on the status line.

Index

You can also tab to a keyword to select it.

The Help I Index command opens a dialog box displaying a full list of help keywords (the special highlighted text in help screens that let you quickly move to a related screen).

You can scroll the list or you can incrementally search it by pressing letters from the keyboard. For example, to see what's available under "printing," you can type p r i.

When you type p, the cursor jumps to the first keyword that starts with

When you then type r, the cursor then moves to the first keyword that starts with

pro

When you then type

the cursor moves to the first keyword that starts with

pri,

and so on.

When you find a keyword that interests you, choose it by cursoring to it and pressing

Enter.

(You can also double-click it.)

Topic Search

The Help I Topic Search command displays language help on the currently selected item.

To get language help, position the cursor on an item in an Edit window and choose Topic Search. You can get help on things like function names (printf, for example), header files, reserved words, and so on.

If an item is not in the help system, the help index displays the closest match.

Previous Topic

The Help I Previous Topic command opens the Help window and redisplays the text you last viewed. .

100

Borland

C++

User's Guide

Borland c++ lets you back up through 20 previous help screens.

You can also click on the status line to view the last help screen displayed.

Help on Help

The Help I Help on Help command opens up a text screen that explains how to use the Borland c++ help system. If you're already in help, you can bring up this screen by pressing

F1.

Chapter

Menus and options reference

101

102

Borland

C++

User's Guide

H A p

T E

Building

Windows application

This chapter explains how to use Borland C++ to build Windows applications or dynamic link libraries (DLLs). This chapter does

not

explain the intricacies of designing Windows applications, nor does it teach you how to program under Windows-these topics are far beyond the scope of this chapter or this book.

The basic process

Compiling and linking a module for Windows is basically the same as it is for DOS. The compiler first generates an object file

(which differs from a DOS compilation primarily in the special

Windows prolog and epilog code that wraps each function). The prolog and epilog code varies depending on which Windows compilation options are used; these options are described later.

To create a Windows module for the memory model you are compiling under, the linker links the object files with the appropriate Borland C++ startup code, various libraries, and the module definition file.

Finally, either the IDE, the makefile, or the programmer invokes the Resource Compiler to bind the resources to the module.

Figure 3.1 illustrates the entire process.

The next section, "Compiling and linking with the IDE/' gives you a quick example of how to compile, link, and run a Windows program in the Borland C++ IDE.

If you normally compile and

Chapter

Building

Windows application

103

Figure 3.1

Compiling and linking a Windows program link from the command line or from a makefile, then you should read "Compiling and linking from the command line," starting on page 107.

Compiling and linking within the IDE

You can find complete descriptions of the various

IDE commands and options in Chapter 2.

By way of example, you'll be producing a simple Windows application called WHELLO, which creates a window and writes a text message to that window. WHELLO.EXE is produced by compiling and linking the following three files:

• WHELLO.CPP, the C++ source file

• WHELLO.RC, the resource file

• WHELLO.DEF, the module definition file

104

Borland

C++

User's Guide

Understanding resource files

Windows applications typically use

resources,

which can be icons, dialog boxes, fonts, cursors, and bitmaps. These resources can be created by the Resource Toolkit and are defined in a file called a resource file. For this application, the resource file is

WHELLO.RC .

. RC resource files are source files, also called resource script files.

Before an .RC file can be added to an executable, the .RC file must first be compiled by the Resource Compiler into a binary format; compilation creates a .RES file. For instance, compiling

WHELLO.RC with the Resource Compiler creates WHELLO.RES.

The Resource Compiler is also used to bind .RES resource files to an executable file.

To build a final Windows application, complete with resources, you need to invoke the Resource Compiler in order to bind the

.RES file to the .EXE file. The Resource Compiler does three things:

1. It compiles .RC files to .RES files.

2. It binds the .RES file to the compiled module (.EXE or .DLL).

3. It marks the .EXE or .DLL as Windows-compatible.

Understanding module definition files

Module definition files are described in detail on page

250.

The module definition file WHELLO.DEF provides information to the linker about the contents and system requirements of a Windows application. Because TLINK and the built-in linker have other ways of finding out the information contained in the module definition, module definition files are not required for

Borland C++'s linker to create a Windows application, although one is included here for the sake of example.

Compiling and linking WHELLO

Here's how you tum these three files into a Windows application:

If you haven't done so already, go to the \BORLANDC\

EXAMPLES directory and start the Borland C++ IDE by typing

BCX

(protected mode version) or

BC from the DOS

Chapter

Building

Windows application

105

106 command line. If you are already in the IDE, change to the \

BORLANDC\EXAMPLES directory with File

Change dir.

2. Choose Project

Open Project. In the Project Name box, type

WHELLO.PRJ. Press

Enter

or click OK to open a new project with the name WHELLO.

3. Choose Project I Add item and type whello .

*

in the Name box, so that you'll get a list of all the WHELLO files.

4. Add the three files WHELLO.CPP, WHELLO.RC, and

WHELLO.DEF for the application. Close the Project dialog box after you've added the three files.

5. Choose Options I Application to open the Set Application

Options dialog box. Choose Windows App. The information pane at the top of the dialog box changes. Each of the four buttons at the bottom of the dialog checks and sets several other options in the IDE (see Chapter 2, page 86 for details).

6. Choose Compile

Build all to build the project.

7. Exit the IDE by pressing

Alt-X

or choosing File I Quit.

8. From the DOS command line, type win whello

DOS will load Windows, which will itself run the WHELLO application.

That's all there is to building and running a Windows application with Borland C++. You can generalize this process into the following checklist:

1. Create a project.

2. Add the source files, resource files, import libraries (if necessary), and the module definition file (if necessary) to the project.

3. Set up the compilation and link environment with the Set

Application Options dialog box, or with a combination of other settings and options.

4. Build the project.

5. Run the application under Windows.

Setting compile and link options

The bulk of the setup in this example is accomplished by the Set

Application Options dialog box. The action buttons in this dialog box check or set various other options in other dialog boxes.

Borland C++ makes it easy for you to change the settings that

Bor/and c++

User's Guide

control compilation and linkage of your programs, so you'll want to familiarize yourself with the following dialog boxes (all described in full in Chapter 2):

• The Code Generation dialog box sets such things as the memory model, tells the compiler to use pre-compiled headers, and more. Choose Options I Compiler I Code Generation to see this dialog box.

• The Entry/Exit Code Generation dialog box sets Borland C++ compiler options for prolog and epilog code generation, and export options. Choose Options I Compiler I Entry /Exit Code and browse through the contents of this dialog box.

• The Make dialog box (Options I Make). The Generate Import

Library options allow you to create an import library for a DLL.

An import library makes it possible to declare all of the functions in a DLL as imports to another module without using a module definition file (see Chapter 7, page 192).

• The Linker dialog box (Options I Linker) sets options for the type of output you want from the linker-such as a standard

DOS .EXE, an overlaid DOS .EXE, a Windows .EXE, or a Windows DLL-as well as a number of other linker options.

Compiling and linking from the command line

If you know how to compile and link a C++ or C program for

DOS, then you already know almost all you need to know to do the same thing for Windows. You'll need three files to compile and link the example application:

• WHELLO.CPP, the C++ source code

• WHELLO.DEF, the module definition file

• WHELLO.RC, the resource file

Compiling from the command line

To compile and link WHELLO.CPP for a Windows application, type

Bee -W

whello.cpp

Given this command line, Borland C++ compiles WHELLO.CPP into WHELLO.OBJ, then links in the correct libraries and startup code automatically. To suppress the link phase, add the

-c option

Chapter

Building

Windows application

107

108 to the command line. To include debugging information, add the

-v option.

The

-W

option tells the command-line compiler that you want a

Windows application. There are other Windows options (of the form -Wxxx) that give the compiler more specific instructions about the compilation and code generation of a Windows application (for instance,

-WD

to create a DLL). You can find detailed descriptions of all the command-line options in Chapter

Once the WHELLO application is compiled and linked, the only thing left to do is add the resources. First, compile the

WHELLO.RC file with the command rc -r whello.rc

This produces a WHELLO.RES file (-r instructs the Resource

Compiler to

not

add the result to the executable of the same name). Now, invoke the Resource Compiler again to add the binary resource file to the executable. rc whello.res whello.exe

Actually, the Resource Compiler makes it easier than we've shown here, because it can compile an .RC file into a .RES file and then add it to the executable all in one step. Furthermore, if the executable file has the same first name as the resource file, then you don't need to specify the executable file on the command line at all. So, the previous two commands can be rewritten like this: rc whello

To load Windows and run the application, type win whello

Linking from the command line

To link WHELLO.OBJ with the correct libraries and startup code, invoke TLINK with the following command-line:

TLINK ITw Iv whello

ILC:\BORLANDC\LIB cOws whello, whello, , import cwins cs,

The TLINK command line is composed of options and five file names or groups of file names; each file or group of files is separated by a comma.

Borland

C++

User's Guide

The rrw option means to link for (target) Windows,

tells TLINK to include debugging information, and Ie forces case to be significant in public and external symbols.

IL,

followed by a path name, tells TLINK where to look for library files and for the startup

.OBI

code.

The object files to link are listed next in the command line.

COWS.

OBI

is the initialization module for the small memory model, and WHELLO.OBI is program module for this application.

The

.OBI

extension is assumed for both these files.

The next file on the command line, WHELLO, is the name you want TLINK to give the executable file. The .EXE extension is assumed when you create a Windows application, and the .OLL extension is assumed when you create a OLL. For more details on how TLINK knows whether you want an .EXE or .OLL, see the section "Linker options" on page 116.

The next file on the command line is the name you want to give the map file.

If no name is given, as in this example, TLINK gives the map file the name of the executable and adds the .MAP extension. After you run this command, you'll notice the file

WHELLO.MAP in the examples directory.

The library files to link are listed after the map file. CWINS.Lm is the small memory model run-time library for Windows, CS.LIB is the regular run-time library, and llvIPORT.LIB is the library that provides access to the built-in Windows functions. The .Lm extension is assumed for all library files.

The last file name on the TLINK command line is the module definition file, WHELLO.DEF (the .DEF extension is assumed).

Module definition files are described briefly on page 105, and in detail in Chapter 7, page 250.

Using a makefile

Since you probably won't want to type in the full command lines for the command line compiler and TLINK every time you want to build a Windows application, it's a good idea to create a makefile for your application.

The makefile for the WHELLO application is WHELLO.MAK.

Note that for this example, the libraries are in C:\BORLANDC\

LIB, and the include files are in C: \ BORLANDC\INCLUDE. The following section explains each rule in the makefile.

Chapter

Building

Windows application

109

110

To run MAKE on this makefile, type make -fwhello.mak

The first rule tells MAKE how to make the final executable from

WHELLO.EXE and a WHELLO.RES, and how to make the intermediate executable from the object file and the module definition file. (See the alternate makefile at the end of this section for a more generalized approach to building a Windows application. ) whello.exe: whello.obj whello.def whello.res tlink ITw

Iv In Ic

C:\BORLANDC\L1B\cOws whello,\ whello,\

C:\BORLANDC\L1B\cwins C:\BORLANDC\L1B\cs

C:\BORLANDC\L1B\import,\ whello rc whello.res

The next rule tells MAKE how to make required .OBJ files from

.CPP files of the same name. The options are: make a Windows application

(-W), compile only (-c), use the small memory model

(-ms), and include debugging info (-v) .

. cpp.obj:

BCC -c -ms -v

-w

This last rule tells MAKE how to make required .RES files (final resource files) from .RC files of the same name .

. rC.res: rc -r -iC:\BORLANDC\1NCLUDE $<

The

-r

option tells the Resource Compiler to compile the resources only (instead of also adding them to the executable of the same name). The

-i

options specifies the directory in which to search for include files.

Another makefile for

Windows

The following makefile is a more general-purpose make file than the one shown previously. It can be easily modified by redefining the macros OBJS, INCP ATH, and FLAGS. TLINK is not invoked in a separate rule; instead, BCC invokes TLINK automatically.

OBJS

= whello.obj

1NCPATH

C:\BORLANDC\1NCLUDE

FLAGS

-W -v -1$ (1NCPATH) test.exe: $ (OBJS) whello.def whello.res

Bor/and

C++

User's Guide

BCC $ (FLAGS) -ewhello.exe @&&!

(OBJS) rc whello.res

.c.obj:

BCC -c $ (FLAGS) {$< }

. cpp. obj:

BCC -c

(FLAGS)

{$< }

.rc.res: rc -r -i$(INCPATH) $<

Prologs and epilogs

See page

for description and usage of the

_export

keyword.

When you compile a module for Windows, the compiler needs to know which kind of prolog and epilog to create for each of a module's functions. Settings in the IDE and options for the command-line compiler control the creation of the prolog and epilog. The prolog and epilog perform several functions, including ensuring that the correct data segment is active during callback functions, and marking near and far stack frames for the

Windows stack-crawling mechanism.

The need for prologs and epilogs is not new to Windows; they must be generated for code intended for DOS as well. However, if the program is intended for Windows, the compiler generates a different prolog and epilog than it would for DOS.

The prolog and epilog code is automatically generated by the compiler, though various compiler options or IDE options dictate the exact instructions contained in the code.

The following list describes the effects of the different

Prolog/Epilog Code Generation options and their corresponding command-line compiler options. To set these options in the IDE, choose Options I Compiler I Entry/Exit Code .

• Windows All Functions

Exportabl~

(-W). This option creates a

Windows application object module with all far functions exportable.

This is the most general kind of Windows application module, although not necessarily the most efficient. The compiler generates a prolog and epilog for every far function that makes the function exportable. This does not mean that all far

Chapter

Building

Windows application

111

112 functions actually will be exported, it only means that the function can be exported.

In order to actually export one of these functions, you must either use the

_export

keyword or add an entry for the function name in the EXPORTS section of the module definition file .

• Windows Explicit Functions Exported (-WE). This option creates an object module with only those functions marked as

_export

exportable.

Since, in any given application module, many of the functions will not be exported, it is not necessary for the compiler to include the special prolog and epilog for exportable functions unless a particular function is known to be exported. The

_export

keyword in a function definition tells the compiler to use the special prolog and epilog required for exported functions. All functions not flagged with

_export

receive abbreviated prolog and epilog code, resulting in a smaller object file and slightly faster execution.

Note that the Windows explicit functions exported option

only

works in conjunction with the

_export

keyword. This option does not export those functions listed in the EXPORTS section of a module definition file. In fact, you can't use this option and provide the names of the exported functions in the EXPORTS section. If you do, the compiler will generate prolog and epilog code that is incompatible with exported functions; incorrect behavior will result when these functions are called .

• Windows Smart Callbacks

(-WS).

This option creates an object module with functions using smart callbacks.

This form of prolog and epilog makes use of the assumption that DS

SS; in other words, that the default data segment is the same as the stack segment; this eliminates the need for the special Windows code (called a thunk) that is created for exported functions. This form of prolog and epilog can improve performance because calls to functions in the module do not have to be redirected through the thunks.

Exported functions here do not need the

_export

keyword, and do not need to be listed in the EXPORTS section of the module definition file, because the linker does not need to create an export entry for them in the executable.

When you use functions compiled and linked with smart callbacks, you do not need to precede them with a call to

MakeProcInstance (which rewrites the function's prolog in such a way that it uses a smart callback).

Borland

C++

User's Guide

There are

smart col/backs for DLLs since DLLs assume

/=$$.

Because of the assumption that DS

SS, you can't use this option for modules in a DLL (applications are fine, but not

DLLs). Furthermore, you must not explicitly change DS in your program (not a very safe practice under Windows in any circumstance) .

• WindowsDLL All Functions Exportable (-WO). This option creates a DLL object module with all functions exportable.

This prolog and epilog code is used for functions which will reside in a DLL.

It also supports the exporting of these functions. This is similar to the corresponding non-DLL option,

Object Module With All Functions Exportable .

• Windows DLL Explicit Functions Exported (-WDE).

This prolog and epilog code is used for functions which will reside in a DLL. However, any functions which are to be exported must explicitly specify _export in the function definition. This is similar to the corresponding non-DLL option,

Object module with only explicitly designated functions exportable.

The _export keyword

The keyword _export in a function definition is used to tell the compiler to compile the function as exportable. It also tells the linker to export the function. In a function declaration, _export immediately precedes the function name; for example,

LONG FAR PASCAL _export MainWindowProc( HWND hWnd, unsigned iMessage,

WORD wParam, LONG IParam )

You can also use _export with a C++ class definition; see page

127.

Prologs, epilogs, and exports: a summary

There are two steps to exporting a function. First, the compiler must create the correct prolog and epilog for the function; if so, the function is called exportable. Second, the linker must create an entry for every export function in the header section of the executable. All of this occurs so that the correct data segment can be bound to the function at run-time.

If a function is flagged with the _export keyword and any of the

Windows compiler options is used, it will be compiled as exportable and linked as an export.

Chapter

Building

Windows application

113

If a function is

not

flagged with the

_export

keyword, then

Borland c++ will take one of the following actions:

• If you compile with the

-W or -WD

option (or with the IDE equivalent of either option), the function will be compiled as exportable.

If the function is listed in the EXPORTS section of the module definition file; then the function will be linked as an export.

If it is not listed in the module definition file, or if no module definition file is linked, then it won't be linked as an export.

• If you compile with the

-WE or

-WOE

option (or with the IDE equivalent of either option), the function will

not

be compiled as exportable. Including this function in the EXPORTS section of the module definition will cause it be exported, but, because the prolog is incorrect, the program will run incorrectly. You may get the Windows error message, "Unrecoverable application error".

The following table summarizes the

~ffect of the combination of the Windows compiler options and the

_export

keyword:

114

Borland

C++

User's Guide

Table 3.1: Compiler options and the _export keyword

Function flagged with _export?

Function listed in EXPORTS?

And the compiler option is:

Will function be exportable?

Will function be exported?

Yes

Yes*

-Wor -WE or -Wor -WE or -Wor -WE or -Wor -WE or

-WO -WOE -WO -WOE -WO -WOE -WO -WOE

Yes

No**

The function will be exported in some sense, but, because the prolog and epilog won't be correct, the function won't work as expected.

This combination also makes little sense. It's inefficient to compile all functions as exportable if you don't actually export some of them.

Memory models

You can use the small, medium, compact, or large memory models with any kind of Windows executable, including DLLs.

Do not use the tiny or the huge model for any Windows executable. Borland C++ doesn't restrict you from setting the tiny or huge model either on the command line or in the IDE, but the code that is generated won't work under Windows. See the section "Linking .OBJ and .LIB files for DLLs" on page 118 for more information.

Linking for Windows

In general, Borland C++ needs to take object files compiled with the correct Windows options and then link them with the proper

Windows initialization code, run-time and math libraries, and a module definition file. Settings in the Linker dialog box in the IDE do this for you automatically; if you use TLINK, you must specify all the options and files.

Chapter

Building

Windows application

115

Linking in the IDE

With the Linker dialog box in the IDE, you can set link options for a Windows application or DLL. Options in the IDE override settings in the module definition file. This means if you check the

Windows EXE box instead of the Windows DLL box, and the module definition file has a LIBRARY statement instead of a

NAME statement, the file will be linked as a Windows application, not a DLL.

The linker uses the

COWx.OBJ

initialization file for applications and the

CODx.OBJ

initialization file for DLLs, where

depends on the memory model set in the Code Generation dialog box. For both Windows options, the linker· uses the current project object files and libraries, IMPORT. LIB, CWINx.LIB, MA THx.Lffi, and

Cx.LIB.

Borland C++ allows you to override the default setting for a memory model, even with an incorrect model. See the discussion of the Code Generation dialog box on page 61.

Linking with TLiNK

starting with this version,

TLINK is sensitive to the case of its options.

TLINK is discussed in detail in Chapter 7, "Utilities". This section discusses only those aspects of TLINK that affect linking a Windows executable.

To provide a way to link a module definition file, the new syntax of the TLINK command line is:

TLINK

objjiles, exejile, mapjile, libjiles, deffile

For a list of TLINK messages (errors and warnings), see Chapter

Linker options There are three options that you can pass to TLINK to control its linkage of Windows executables and DLLs .

• Use the

ITw

option to create a Windows .EXE or .DLL according to the settings in the module definition file. If you have a

NAME statement in the module definition file, TLINK will link it as a Windows executable; if you have a LffiRARY statement in the .DEF file, the files will be linked as a DLL.

If no module definition file is specified on the TLINK command line, this option causes the files to be linked as a Windows .EXE.

116 Bor/and C++ User's Guide

You don't need this option if you are using a module definition file in which the EXETYPE statement specifies WINDOWS .

• Use the ITwe option to specify a Windows executable. This overrides settings in the module definition file. For instance, even if you have a LIBRARY statement in the include .DEF file,

TLINK will link the files as an .EXE.

Use the ITwd option to specify a Windows DLL. This overrides settings in the module definition file.

When you're linking a Windows executable, do

not

use the b option to overlay files, or the

or ITde option to make a .COM file.

Linking .OBJ and .LlB files

The list of object files must begin with the file

COWx.OBJ

CODx.OBJ

(for DLLs), followed by the names of the other object files to link. User libraries and IMPORT. LIB can be included anywhere on the list, although, by convention, they are usually listed before the standard libraries. The other required libraries must be in this order:

Important! Do not link in

EMU.LlB or FP87.LlB. Borland

C++ takes care of the

floating-point math automatically.

.. CWINx.LIB

MATHx.LIB

.Cx.LIB

To create a Windows application executable, you might use this response file, named WINRESP:

ITw

\BORLANDC\LIB\COWS winappl winapp2 winapp winapp

\BORLANDC\LIB\IMPORT \BORLANDC\LIB\CWINS \BORLANDC\LIB\CS

;,rinapp.def where

• The ITw option tells TLINK to generate a Windows application or DLL. If a module definition file were not included in the link,

TLINK would create a Windows application. If the module definition file is included and it contains instructions to create a

DLL, then TLINK will create a DLL.

• The

option tells TLINK to be sensitive to case during linking.

• \BORLANDC\LIB\COWS is the standard Windows initialization file and WINAPPl and WINAPP2 are the module's object files.

• WINAPP is the name of the target Windows executable.

Chapter

Building

Windows application

117

• TLINK will name the map file WINAPP.MAP.

• \BORLANDC\LIB\CWINS is the small memory model runtime library for Windows, LIB\CS is the regular run-time library, and \ BORLANDC \ LIB \ IMPORT is the library that provides access to the built-in Windows functions.

• WINAPP.DEF is the Windows module definition file for the object files named.

To use this response file on the TLINK command line, type

TLINK @winresp

. . After linking the application or DLL, you

must

invoke the

Resource Compiler to add resources to the image. The Windows

3.x

Resource Compiler also marks the image as Windows

3.x

compatible. Even if you have no resources, you need to run the

Resource Compiler.

Linking .OBJ and .LlB You need to link different .OBJ and .LIB files for a DLL than for a files for DLLs

Windows application. If the linker is invoked either from the IDE or from the command-line compiler BCC or BCCX, the correct

.OBJ and .LIB files will be linked in automatically. If you invoke

TLINK explicitly, then you need to know which files to link in for a DLL. The following table summarizes the memory models, startup files, and hbraries:

Table 3.2

Startup and library files for

DLLs

Model

Small

Compact

Medium

Large

Startup file

CODS.OBJ

CODC.OBJ

CODM.OBJ

CODL.OBJ

Library

CWINC.Lffi

CWINL.Lffi

The compact memory model library is used for both small and compact because it creates far data pointers and near code pointers. The large memory model library is used for both medium and large because it creates far data pointers as well as far code pointers. DLLs can only have far pointers to data; near pointers are not allowed.

Building a project for a Windows program

You can use the Project Manager to build Windows applications and DLLs. Building a Windows program usually requires adding

118

Borland

C++

User's Guide

a module definition file (.DEF) and resource file (.RC or .RES) to the project.

Specifying an .RC file is similar to specifying a source file in a project. The Project Manager will invoke the Resource Compiler once to compile it to an .RES file, and a second time to bind the

.RES to the module and to mark the module as Windowscompatible. Specifying an .RES file is similar to specifying an object file. The Project Manager will invoke the Resource

Compiler only to bind it to the module and to mark the module as

Windows-compatible.

For example, if you enter HELLO.CPP, HELLO.RC, and

HELLO.DEF into a project, the Borland C++ Project Manager will

• create HELLO.

OBI

by compiling HELLO.CPP with the C++ compiler

• create HELLO. RES by compiling HELLO.RC with the Resource

Compiler

• create HELLO.EXE by linking HELLO.

OBI

with its appropriate libraries, using information contained in HELLO.DEF

• create the final HELLO.EXE by using the Resource Compiler to bind the resources contained in HELLO. RES to HELLO.EXE

When you add an .RC file to a project, the Project Manager automatically assigns the default translator to be the Resource

Compiler. In addition, the default output name is

file.

RES (not

file.OBI).

Finally, "Exclude from Link" is selected because TLINK should not link the resulting .RES file.

During a make, the Project Manager recompiles the .RC file if it is newer than the .RES file, in the same way that it recompiles

HELLO.C if it is newer than HELLO.

OBI.

No autodependencies are checked because that information is not available.

During a make, the Project Manager runs the Resource Compiler after any relink because the Resource Compiler also marks the image as Windows

3.x

compatible. Even if you have no resources, you need to run the Resource Compiler.

The Project Manager will not attempt to compile a file with the

.DEF extension.

Chapter

Building

Windows application

119

WinMain

The Win Main function is the main entry point for a Windows application; you must supply it.

The following parameters are passed to Win Main: int PASCAL WinMain(HANDLE hlnstance, HANDLE hPrevlnstance,

LPSTR IpCmdLine, int nCmdShow)

The HANDLE and LPSTR types are defined in windows.h.

HANDLE

hlnstance

is the instance handle of the application. Each instance of a Windows application will have a unique instance handle. This handle is used as an argument to several Windows functions and can be used to distinguish between multiple instances of a given application.

HANDLE

hPrevlnstance

is the handle of the previous instance of this application.

hPrevlnstance

is NULL if this is the first instance.

LPSTR

lpCmdLine

is a far pointer to a null-terminated command line string. This value can be specified when invoking the application from the program manager or from a call to

Win Exec. int

nCmdShow

is an integer which specifies how to display the application's window. This value should be passed to

ShowWindow. See documentation on ShowWindow for the possible values

nCmdShow

may take on.

The return value from

WinMain

is not currently used by Windows. However, it can be useful during debugging since Turbo

Debugger can display this value upon termination of your program.

The Resource Compiler

The Resource Compiler does three things

• it compiles resource script files (.RC) and the resource files

(.lCD, .CUR, and so on) into a binary file (.RES)

• it binds compiled resources to a compiled and linked application

• it marks the .EXE or .DLL as Windows

3.x

compatible

120

Bor/and

C++

User's Guide

Windows resources are icons, dialog boxes, fonts, menus, cursors, and bitmaps. These resources are created independently of the application or DLL. See the Resource Toolkit for more information on creating resources.

From the IDE, the Resource Compiler is invoked by the Project

Manager when building a Windows project. Any .RC file (source file) included in a project causes Borland C++ to invoke the

Resource Compiler to compile it to a .RES file. Then, after TLINK has linked the project's application or DLL, the Resource Compiler marks and binds the resources to it.

From the command line, you can compile the resource files you want to use in your Windows application with the Resource

Compiler. When you're ready to build the application, you use the

Resource Compiler to bind the .RES file to the .EXE or .DLL.

In a make file, add the .RES file to the list of files in the explicit rule that governs the build of the final .EXE. In that rule, also add the command to invoke the Resource Compiler with the correct

.RES file. You can also add a rule to invoke the Resource Compiler on an out-of-date .RES file. See the example of a make file on page

109.

Resource

Compiler syntax

This is how you invoke the Resource Compiler from the command line:

[options] ResourceFile [ModuleFile]

For example, to compile WHELLO.RC file and add it to

WHELLO.EXE, you would give this command line: rc whello

This simplest form only works if the resource file and the executable file share the same name.

WHELLO.RC was instead named WHELLORS.RC, you would type rc whellors whello

To compile only the WHELLO.RC resource file (and not add the resulting WHELLO.RES to WHELLO.EXE), use the

-R

option, like this: rc -r whello

Chapter

Building

Windows application

121

You would then have a WHELLO.RES file. To add WHELLO.RES to WHELLO.EXE, type rc whello.res

To mark a module as Windows-compatible, but not add any resources to it, simply invoke the Resource Compiler with the module name (note that the file name must have one of these extensions: .EXE, .DLL, or .DRV). For example, rc whello.exe

The following table describes the Resource Compiler options.

Note that Resource Compiler options are not case sensitive (-e is the same as

-E).

Also, options that take no arguments can be combined (for instance, -kpr is legal).

Table 3.3: Resource Compiler options

Option

-d

Symbol

-e

-fe

FileName

-fo

FileName

-h

-i

Path

-k

-I

-lim32

-m

-multinst

-p

-r

-t

-v

-x

What it does

Lists help on Resource Compiler options (also -H).

Defines Symbol for the preprocessor.

Changes location of global memory for a DLL to above the EMS bank line

Renames the .EXE file to

FileName.

Renames the .RES file to

FileName.

Lists help on Resource Compiler options (also -?).

After searching the current directory for include files and resource files, RC searches the directory named in Path. The -i option can be repeated if you want to specify more than one search path. Also see the description for the -x option.

Turns off load optimization for segments and resources. (Normally, the Resource

Compiler preloads all data segments, nondiscardable code segments, and the entry-point code segment, even if the segments were not marked as PRELOAD in the module definition file. In addition, the Resource Compiler normally places all preloaded segments in a contiguous area in the executable file.)

Informs Windows that the application will be using expanded memory, according to the LIM 3.2 specification.

Same as

-I option.

Assigns each instance of a task to a different EMS bank, if the expanded memory under Windows is configured under EMS 4.0.

Same as -m option.

Makes a DLL private to one or more instances of a single application, which might result in performance gains.

Compile the .RC file into a .RES file, but do not add it to an .EXE.

Creates application to be run only in standard mode or 386 enhanced mode

(protected mode). If the user tries to run in real mode, a message will be displayed.

Display all compiler progress messages (compile verbose).

Excludes searching in the directories named in the INCLUDE environment variable.

Also see the description for the -i option.

122

Borland C++ User's Guide

Dynamic link libraries

A dynamic link library (DLL) is a library of functions that a Windows module can call to accomplish a task. If you've written a

Windows application, then you've already used DLLs. The files

KERNEL.EXE, USER.EXE, and GDLEXE are actually DLLs, not applications (as the .EXE extension implies).

The references to the

API functions that you call from these modules are resolved at run time (dynamic linking), instead of at link time (static linking).

Compiling and linking a DLL within the IDE

To compile and link a DLL from within the IDE, follow these steps:

1. Create the DLL source files. Optionally, create the resource file and the module definition file.

2. Choose Project

Open to start a new project.

3. Choose Project

Add item, and add the source and resource files for the DLL.

4. If you have created a module definition file for the DLL, add it to the project. (Note that Borland C++ can link without one.)

5. Choose Options

Application

Windows dynamic link library.

To link without a module definition file for the DLL, you must have flagged every function to be exported in the DLL with the keyword _export. (The _export keyword should immediately precede the function name.) In addition, choose

Options I Compiler I Entry/Exit Code I Windows DLL explicit functions exportable.

6. Choose Compile I Build all.

Compiling and linking a DLL from the command line

To compile and link a DLL composed of the source file

LIBXAMP.CPP, type

Bee -ND libxamp.cpp

The command-line compiler takes care of linking in the correct startup code and libraries. The -WO option tells the compiler to build a Windows DLL with all functions exportable. To compile and link with explicit functions exportable, you would use the

-WOE option and use the _export keyword for export functions.

Chapter

Building

Windows application

123

To link a DLL with the command-line linker TLINK, you might use this command line

TLINK ITwd Iv import,libxamp

ILC:\BORLANDC\LIB cOds libxamp, libxamp, , cwinc cs

The

ITwd

option indicates a Windows DLL,

tells TLINK to include debugging information, and Ie forces case to be significant in public and external symbols. The IL option specifies a library and startup file search path.

See page 118 for an explanation of the library and object files needed to link a DLL.

Module definition files A module definition file is not strictly necessary to link either a

DLL or a Windows application. See page 250 for information on default module definition file replacement settings.

There are two ways to tell the linker about export functions:

• To link with a module definition file, create an EXPORTS section in the module definition file that lists all the functions that will be used by other applications. (A utility called

IM:PDEF can help you do this, see page 190.)

• To link without a module definition file, you must flag every function to be exported in the DLL with the keyword _export.

In addition, when you build or link the DLL, you must choose

Options I Compiler I Entry/Exit Code I Windows DLL Explicit

Functions Exportable.

A function must be exported from a DLL before it can be imported to another DLL or application.

Import libraries If a Windows application module or another DLL uses functions from a DLL, you have two ways to tell the linker about them:

• You can add an IM:PORTS section to the module definition file and list every function from DLLs that the module will use.

• Or you can include the import library for the DLLs when you link the module. (A utility called IM:PLIB creates an import library for one or more DLLs; see page 192 for details.)

124 Borland

C++

User's Guide

Creating DLLs

The following sections provide information on the specifics of writing a DLL.

LibMain and WEP The

LibMain

function is the main entry point for a Windows DLL; you must supply it yourself.

Windows calls

LibMain

once, when the library is first loaded.

LibMain

performs initialization for the DLL. This initialization depends almost entirely on the function of the particular DLL, but might include the following tasks:

Note

• Unlocking the data segment with

UnlockData,

if it has been declared as MOVEABLE

• Setting up global variables for the DLL, if it uses any

• Registering Windows for the DLL

The DLL startup code CODx.OBJ initializes the local heap automatically; you do not need to include code in

LibMain

to do this.

This function is called by Windows (actually by the run-time library) upon DLL initialization. You must supply it when building a DLL. The following parameters are passed to

LibMain:

int PASCAL LibMain (HANDLE hInstance, WORD wDataSeg,

WORD cbHeapSize, LPSTR lpCmdLine)

HANDLE, WORD, and LPSTR are defined in windows.h

HANDLE

hlnstance

is the instance handle of the DLL.

WORD

wDataSeg

is the value of the data segment (DS) register.

WORD

cbHeapSize

is the size of the local heap specified in the module definition file for the DLL.

LPSTR

IpCmdLine

is a far pointer to the command line specified when the DLL was loaded. This is almost always null since DLLs are typically loaded automatically with no parameters. It is possible, however, to supply a command line to a DLL when it is loaded explicitly.

The return value for

LibMain

is either 1 (successful initialization) or 0 (failure in inititalization). If 0, Windows will unload the DLL from memory.

Chapter

Building

Windows application

125

The exit point of a DLL is the function

WEP

(which stands for

Windows exit procedure). This function is not necessary in a DLL

(since the Borland c++ run-time libraries provide a default one) but can be supplied by the writer of a DLL to perform any cleanup of the DLL before it is unloaded from memory. Windows will call the

WEP

procedure just prior to unloading the DLL.

WEP

should perform any cleanup required for the DLL. Under

Borland

C++,

WEP

does not need to be exported. Borland

C++ defines its own

WEP

that calls your

WEP,

and then performs system cleanup. This is the prototype for

WEP:

int FAR PASCAL REP (int nPararneter)

int

nParameter

is either WEP _SYSTEMEXIT or WEP _FREE_DLL.

The former means that all of Windows is shutting down and the latter indicates that just this DLL is being unloaded.

WEP

should return 1 to indicate success. Windows currently doesn't do anything with this return value.

Pointers and memory Functions in a DLL are not linked directly into a Windows application, they are called at run time. This means that calls to

DLL functions will be far calls, because the DLL will have a different code segment than the application. The data used by called DLL functions will need to be far as well.

Let's say you have a Windows application called APPi, a DLL defined by LSOURCE1.C, and a header file for that DLL called lsource1.h. Function

f1,

which operates on a string, is called by the application.

If you want the function to work correctly regardless of the memory model the DLL will be compiled under, you need to explicitly make the function and its data far. In the header file, the function prototype would take this form: extern FAR f(char FAR *dstring);

In the DLL, the implementation of the function would take this form: far fl(char far *dstring)

{

For the function to be used by the application, the function would also need to be compiled as exportable and then exported. To

126

Bor/and

C++

User's Guide

accomplish this, you can either compile the DLL with all functions exportable

(-WD)

and list f1 in the EXPORTS section of the module definition file, or you can flag the function with the

_export keyword, like so: far _export fl(char far *dstring)

{

If you compile the DLL under the large model (far data, far code), then you don't need to explicitly define the function or its data far in the DLL. In the header file, the prototype would still take this form extern FAR f(char FAR *dstring); because the prototype would need to be correct for a module compiled with a smaller memory model. But in the DLL, the function could be defined like this:

_export fl(char *dstring)

{

Static data in DLLs

Through a DLL's functions, all applications using the DLL have access to that DLL's global data. A particular function will use the same data, regardless of the application that called it. If you want a DLL's global data to be protected for use by a single application, you would need to write that protection yourself. The DLL itself does not have a mechanism for making global data available to a single application. If you need data to be private for a given caller of a DLL, you will need to dynamically allocate the data and manage the access to that data manually. Static data in a DLL is global to all callers of a DLL. c++ classes and pointers

C++ class that is used only inside a DLL does not need to be declared as far. If the class is to be used from another DLL or a

Windows application, then it requires special handling.

All of the the data members and member functions of a shared class need to be far. This can be accomplished by declaring the class members as

far

or compiling the DLL under the large

Chapter

Building

Windows application

127

128 memory model. The classes also must be exported, which can be accomplished two different ways:

• either include the names of all the class members in the

EXPORTS section of the module definition file, then compile the DLL with the compiler option that makes all functions exportable

(-WD)

• or mark the entire class with the _export keyword, and compile the DLL with the compiler option that makes explicit functions exportable

(-WDE) c++ classes use virtual table pointers and include a hidden this pointer. Both of these pointers need to be far pointers as well.

There are two basic ways to accomplish this.

One way is to simply compile the DLL modules and the application using the DLL with the Far C++ Virtual Table Pointers option (Options I Compiler I C++ options in the IDE or

-Vf from the command line). This causes all virtual table pointers and this parameters to be full 32-bit pointers. The advantage of this approach is that it does not require any source code changes. It may be less efficient than possible, though; all classes, shared or not, suffer the overhead of 32-bit pointers.

A more efficient approach is to declare the shared classes huge instead of far. This tells the compiler to use full 32-bit pointers for those classes only. Note that a huge class can only inherit from other huge classes. Here is an example of a huge class declaration: class huge DLLclass

{ etc ...

};

For a class that is defined in a DLL to be usable from a Windows application, its non-inline member functions and static data members must be made available by making them exported names. This can be done by adding their public (mangled) names to the EXPORTS section of the DLL module definition file, but this can be rather tedious.

There's an easier alternative: declare the classes to be exported as

_export. Whenever a class is declared as _export, Borland C++ treats it as huge (with 32-bit pointers), and automatically exports all of its non-inline member functions and static data members. If

Borland

C++

User's Guide

you declare a class as _export, you can't also declare it as

far

or huge. Lexport implies huge, which implies far.)

If you declare the class in an include file that is included both by the DLL source files and by the source files of the application using the DLL, such a class should be declared _export when compiling the DLL, and merely

huge

when compiling the application. To do this, you can use the __ DLL __ macro, which is defined by the compiler when it's building a DLL. The following code could be a part of an include file that defines a shared class:

#ifdef DLL

#define EXPORT _export

#else

#define EXPORT huge

#endif class EXPORT DLLclass

{

... etc ...

};

Note that the compiler encodes (in the mangled name) the information that a given class member is a member of a huge class. This ensures that when a program using huge and nonhuge classes is linked, any mismatches are caught by the linker.

Chapter

Building

Windows application

129

130

Borland

C++

User's Guide

A p

Managing multi-file projects

Since most programs consist of more than one file, having a way to automatically identify those that need to be recompiled and linked would be ideal. Borland C++'s built-in Project Manager does just that and more.

The Project Manager allows you to specify the files belonging to the project. Whenever you rebuild your project, the Project

Manager automatically updates the information kept in the project file. This project file, which includes

• all the files in the project

• where to find them on the disk

• which files depend on which other files being compiled first

(auto-dependency issues)

• which compilers and command-line options need to be used when creating each part of the program

II where to put the resulting program

,. code size, data size, and number of lines from the last compile

Using the Project Manager is easy. To build a project,

• pick a name for the project file (from Project I Open Project)

• add source files using the Project I

Add

Item dialog box

• tell Borland C++ to Compile I Make EXE File

Then, with the project-management commands available on the

Project menu, you can

Chapter

Managing multi-file projects

131

All the files In this chapter are in the Examples directory.

• add or delete files from your project

• set options for a file in the project

• view included files for a specific file in the project

Let's take a look at an example of how the Project Manager works.

Using the project manager

If you have project files from

Turbo

use the utility

PRJCNVT.EXE to convert them,' for details, see

UTfL.DOC on disk.

Suppose you have a program that consists of a main source file,

MYMAIN.C, a support file, MYFUNCS.C, that contains functions and data referenced from the main file, and myfuncs.h.

MYMAIN.C looks like this: tinclude <stdio.h>

Unclude "myfuncs.h" main (int argc, char *argv[))

{ char *s; if

(argc > 1) s

= argv[l); else s

"the universe"; printf("%s %s.\n",GetString(),s);

MYFUNCS.C looks like this: char ss [)

"The restaurant at the end of"; char *GetString(void)

{ return ss;

And myfuncs.h looks like this: extern char *GetString(void);

These files make up the program that we'll now describe to the

Project Manager.

132

Borland C++ User's Guide

These names can be the same (except for the extensions), but they don't have to be. The name of your executable file (and any map file produced by the linker) is based on the project file:Sname.

The first step is to tell Borland C++ the name of the project file that you're going to use: Call it MYPROG.PRJ. Notice that the name of the project file is not the same as the name of the main file (MYMAIN.C). And in this case, the executable file will be

MYPROG.EXE (and if you choose to generate it, the map file will be MYPROG.MAP).

Press

Alt-P

to go to the Project menu and choose Open Project. This brings up the Load Project File dialog box, which contains a list of all the files in the current directory with the extension .PRJ, and date, time, and size information about the first project file. Since you're starting a new file, type in the name

MYPROG in the Load

Project File input box.

Notice that once a project is opened, the Add Item, Delete Item,

Local Options, and Include Files options are enabled on the

Project menu.

If the project file you load is in another directory,"the current directory will be set to where the project file is loaded.

You can keep your project file in any directory; to put it somewhere other than the current directory, just specify the path as part of the file name. (You must also specify the path for source files if they're in different directories.) Note that all files and corresponding paths are relative to the directory where the project file is loaded from. After you enter the project file name, you'll see a Project window.

You can change the filename specification to whatever you want with the

Name input box,'

C is the

default.

The Project window contains the current project file name

(MYPROG) and information about the files you've selected to be part of your current project. For each file, the name and path

(location) are shown. Once the file is compiled, it also shows the number of lines in the file and the amount of code and data in bytes generated by the compiler.

The status line at the bottom of the screen shows which actions can be performed at this point:

gives you help,

Ins

adds files to the Project,

Del

deletes a file from the Project,

Ctrl-O

lets you select options for a file,

Spacebar

lets you view information about the include files required by a file in the Project,

Enter

opens an editor window for the currently selected file, and

F10

takes you to the main menu. Press

Ins

now to add a file to the project list.

The Add Item to Project List dialog box appears; this dialog lets you select and add source files to your project. The Files list box shows all files with the .C extension in the current directory.

(MYMAIN.C and MYFUNCS.C both appear in this list.) Three action buttons are available: Add, Cancel, and Help.

Chapter

Managing multi-file projects

133

If you copy the wrong file to the Project window, press Esc to return to the Project window, then Del to remove the current file (marked with a.) from the list.

Note that the Add button commits your change; pressing Esc when you're in the dialog box just puts the dialog box away.

Since the Add button is the default, you can place a file in the

Project window by typing its name in the Name input box and pressing

Enter

or by choosing it in the Files list box. You can also search for a file in the Files list box by typing the first few letters of the one you want. In this case, typing my should take you right to MYFUNCS.C; press

Enter.

You'll see that MYFUNCS gets added to the Project window and then you're returned to the Add Item dialog box to add another file. Go ahead and add MYMAIN.C.

Borland c++ will compile files in the exact order they appear in the project.

Press

Esc

to close the dialog box and return to the Project window.

Notice that the Lines, Code, and Data fields in the Project window show n/ a. This means the information is not available until the modules are actually compiled.

I;:

File Edit Search Proj ect Opt ions Wi ndow Help

-----------------1~

===4=I.t]'91

134

After all compiler options and directories have been set, Borland

C++ will know everything it needs to know about how to build the program called MYPROG.EXE using the source code in

MYMAIN.C, MYFUNCS.C, and myfuncs.h. Now you'll actually build the project.

You can also view your output by choosing

Window I Output.

Press

FlO

to go to the main menu. Now make MYPROG.EXE by pressing

(or choose Compile I Make EXE File). Then run your program by pressing

Ctrl-F9

(or choose

Run

I

Run). To view your output, choose Window I User Screen (or press

Alt-F5),

then press any key to return to the IDE.

Borland

C++ User's Guide

For more information on .PRJ and .DSK files, refer to the section, "Project and configuration files," in

Chapter

When you leave the IDE, the project file you've been working on is automatically saved on disk; you can disable this by unchecking Project in the Preferences dialog box (Options I Environment).

The saved project consists of two files: the project file (.PRJ) and the desktop file (.DSK). The project file contains the information required to build the project's related executable (.EXE). The build information consists of compiler options,

INCLUDE/LIB/OUTPUT paths,linker options, make options, and transfer items. The desktop file contains the state of all windows at the last time you were using the project.

You can specify

project to load on the DOS command line like this:

myprog.prj.

The next time you use Borland C++, you can jump right into your project by reloading the project file. Borland C++ automatically loads a project file if it is the only .PRJ file in the current directory; otherwise the default project and desktop (TCDEF.*) are loaded.

Since your program files and their corresponding paths are relative to the project file's directory, you can work on any project by moving to the project file's directory and bringing up Borland

C++. The correct file will be loaded for you automatically. If no project file is found in the current directory, the default project file is loaded.

Error tracking

As with single-file programs, syntax errors that generate compiler warning and error messages in multifile programs can be selected and viewed from the Message window.

To see this, let's introduce some syntax errors into the two files,

MYMAIN.C and MYFUNCS.C. From MYMAIN.C, remove the first angle bracket in the first line and remove the c in

char

from the fifth line. These changes will generate five errors and two warnings in MYMAIN.

In MYFUNCS.C, remove the first

from return in the fifth line.

This change will produce two errors and one warning.

Changing these fifes makes them out of date with their object files, so doing

make will recompile them.

Since you want to see the effect of tracking in multiple files, you need to modify the criterion Borland C++ uses to decide when to stop the make process. This is done by setting a radio button in the Make dialog box (Options

Make).

Chapter

Managing multi-file projects

135

Stopping a make

You can choose the type of message you want the make to stop on by setting one of the Break Make On options in the Make dialog box (Options I Make). The default is Errors, which is normally the setting you'd want to use. However, you can have a make stop after compiling a file with warnings, with errors, or with fatal errors, or have it stop before it tries to link.

The usefulness of each of these modes is really determined by the way you like to fix errors and warnings.

If you like to fix errors and warnings as soon as you see them, you should set Break

Make On to Warnings or maybe to Errors. If you prefer to get an entire list of errors in all the source files before fixing them up, you should set the radio button to Fatal Errors or to Link. To demonstrate errors in multiple files, choose Fatal Errors in the Make dialog box.

Syntax errors in multiple source files

Since you've already introduced syntax errors into MYMAIN.C and MYFUNCS.C, go ahead and press

(Make) to "make the project." The Compiling window shows the files being compiled and the number of errors and Warnings in each file and the total for the make. Press any key when the

Errors: Press any key message flashes.

Your cursor is now positioned on the first error or warning in the

Message window.

If the file that the message refers to is in the editor, the highlight bar in the Edit window shows you where the compiler detected a problem. You can scroll up and down in the

Message window to view the different messages.

Note that there is a "Compiling" message for each source file that was compiled. These messages serve as file boundaries, separating the various messages generated by each module and its include files. When you scroll to a message generated in a different source file, the Edit window will only track in files that are currently loaded.

Thus, moving to a message that refers to a file that is not loaded causes the Edit window's highlight bar to tum off. Press

Spacebar

to load that file

and

continue tracking; the highlight bar will reappear. If you choose one of these messages (that is, press

Enter

when positioned on it), Borland C++ loads the file it references

136

Borland

C++ User's Guide

into an Edit window and places the cursor on the error. If you then return to the Message window (press

Alt-W

M), tracking resumes in that file.

The Source Tracking options in the Preferences dialog box

(Options I Environment) help you determine which window a file is loaded into. You can use these settings when you're message tracking and debug stepping.

Note that Previous message and Next message

(Alt-F7

and

Aft-F8)

are affected by the Source Tracking setting. These commands will always find the next or previous error and will load the file using the method specified by the Source Tracking setting.

Saving or deleting messages

Normally, whenever you start to make a project, the Message window is cleared out to make room for new messages. Sometimes, however, it is desirable to keep messages around between makes.

Consider the following example: You have a project that has many source files and your program is set to stop on Errors. In this case, after compiling many files with warnings, one error in one file stops the make. You fix that error and want to find out if the compiler will accept the fix. But if you do a make or compile again, you lose your earlier warning messages. To avoid this, check Save Old Messages in the Preferences dialog box (Options I

Environment). This way the only messages removed are the ones that result from the files you recompile. Thus, the old messages for a given file are replaced with any new messages that the compiler may generate.

You can always get rid of all your messages by choosing

Compile I Remove Messages, which zaps all the current messages.

Unchecking Save Old Messages and running another make will also get rid of any old messages.

The power of the Project Manager

When you made your previous project, you dealt with the most basic situation: a list of C source file names. The Project Manager provides you with a lot of power to go beyond this simple situation.

Chapter

Managing multi-file projects

137

Autodependency checking

The Project Manager collects auto dependency information at compile time and caches these so that only files compiled outside the IDE need to be processed. The Project Manager can automatically check dependencies between source files in the project list

(including files they themselves include) and their corresponding object files. This is useful when a particular C source file depends on other files. It is common for a C source to include several header files (.h files) that define the interface to external routines.

If the interface to those routines changes, you'll want the file that uses those routines to be recompiled.

If you've checked the Auto-Dependencies option (Options I Make),

Make obtains time-date stamps for all .C files and the files included by these. Then make compares the date/time information of all these files with their date/time at last compile. If any date/time is different, the source file is recompiled.

If the Auto-Dependencies option is unchecked, the .C files are checked against

.OBI

files. If earlier.C files exist, the source file is recompiled.

When a file is compiled, the IDE's compiler and the command-line compiler put dependency information into the

.OBI

files. The

Project Manager uses this to verify that every file that was used to build the

.OBI

file is checked for time and date against the time and date information in the

.OBI

file. The.C source file is recompiled if the dates are different.

That's all there is to dependencies. You get the power of more traditional makes while avoiding long dependency lists.

Using different file translators

So far you've built projects that use Borland c++ as the only language translator. Many projects consist of both C code and assembler code, and possibly code written in other languages. It would be nice to have some way to tell Borland C++ how to build such modules using the same dependency checks that we've just described. With the Project Manager, you don't need to worry about forgetting to rebuild those files when you change some of

138

Borland C++ User's Guide

the source code, or about whether you've put them in the right directory, and so on.

For every source file that you have included in the list in the

Project window, you can specify

• which program (Borland C++, TASM, and so on) is to be used to make its target file

• which command-line options to give that program

• whether the module is to be an overlay

• what the resulting module is called and where it will be placed

(this information is used by the project manager to locate files needed for linking)

• whether the module should contain debug information

• whether the module should be included in the link

By default, the IDE's compiler is chosen as the translator for each module, using no command-line override options, using the

Output directory for output, assuming that the module is not an overlay, and assuming that debug information is not to be excluded.

Let's look at a simple example. Go to the Project window and move to the file MYFUNCS.C. Now press

Ctrl-O

to bring up the

Override Options dialog box for this file:

Chapter

Managing multi-file projects

139

140

Except for Borland C++, each of the names in the Project File

Translators list box is a reference to a program defined in the

Transfer dialog box (Options I Transfer).

Press

Esc,

then

F10

to return to the main menu, then choose

Options I Transfer. The Transfer dialog box that appears contains a list of all the transfer programs currently defined. Use the arrow keys to select Turbo Assembler and press

Enter.

(Since the Edit button is the default, pressing

Enterbrings

up the Modify/New

Transfer Item dialog box.) Here you see that Turbo Assembler is defined as the program TASM in the current path. Notice that the

Translator check box is marked with an X; this translator item is then displayed in the Override Options dialog box. Press

Esc

to return to the Transfer dialog box.

Suppose you want to compile the MYFUNCS module using the

Borland C++ command-line compiler instead of the IDE's compiler. To do so, you would perform the following steps:

1. First, you need to define BCC as one of the Project File

Translators in the Transfer dialog box. Cursor past the last entry in the Program Titles list, then press

Enter

to bring up the

Modify /New Transfer Item dialog box. In the Program Title input box, type

Borland Ctt Command-Line Compiler; in the

Program Path input box, type

BCC; and in the command line, type

$EDNAME.

2. Then check Translator by pressing

Spacebar

and press

Enter

(New is the default action button). Back at the Transfer dialog box, you see that Borland C++ command-line

(compiler

doesn't show) is now in the Program Titles list box. Tab to OK and press

Enter.

3. Back in the Project window, press

Ctrl-O

to go to the Override

Options dialog box again. Notice that

Borland c++ Command-

Line Compiler

is now a choice on the Project File Translators list for MYFUNCS.C (as well as for all of your other files).

Tab to the Project File Translators list box and highlight

Borland C++ Command-Line Compiler

(at this point, pressing

Enter

or tabbing to another group will choose this entry). Use the Command-Line Options input box to add any commandline options you want to give BCC when compiling

MYFUNCS.

MYFUNCS.C now compiles using BCC.EXE, while all of your other source modules compile with BC.EXE. The Project Manager

Borland

C++ User's Guide

will apply the same criteria to MYFUNCS.C when deciding whether to recompile the module during a make as it will to all the modules that are compiled with BC.EXE.

Overriding libraries

In some cases, it's necessary to override the standard startup files or libraries. You override the startup file by placing a file called

COx.OBJ

as the

first

name in your project file, where

x

stands for any DOS name (for example, COMINE.OBJ). It's critical that the name start with CO, that it is the first file in your project, and that it have an explicit .OBJ extension.

To override the standard library, all you need to do is place a special library name anywhere in the list of names in the Project window. The name of the library must start with a C, followed by a letter representing the model (such as S for the small model); the remaining characters, up to six, can be anything you want for a file name. You must use an explicit .LIB extension (for example,

CSMYFILE.LIB or CSNEW.LIB).

When the standard library is overridden, MAKE will not try to link in the math libraries (based on the Floating Point setting in the Advanced Code Generation dialog box of the Options

Compiler menu).

If you want these libraries linked in when you override the standard library, you must explicitly include them in the Project.

More Project Manager features

Let's take a look at some of the other features the Project Manager has to offer. When you're working on a project that involves many source files, you want to be able to easily view portions of those files, and be able to record notes about what you're doing as you're working. You'll also want to be able to quickly access files that are included by others. The Project Manager provides these features and more.

For example, expand MYMAIN.C to include a call to a function named

GetMyTime:

#include <stdio.h>

#include "myfuncs.h"

Chapter

Managing multi-file projects

141

142

#include "mytime.h" main (int argc, char *argv[])

{ char *s; if

(argc > 1) s else

= argv[l]; s

"the universe"; printf ("%s %s opens at %d. \n", GetString (), s, GetMyTime (HOUR) ) ;

This code adds two include files to

MYMAIN:

myfuncs.h and mytime.h. These files contain the prototypes that define the

GetString and GetMyTime functions, which are called from

MYMAIN.

myfuncs.h contains

extern char *GetString(void);

mytime.h contains

#define HOUR 1

#define MINUTE 2

#define SECOND 3 extern int GetMyTime(int);

Go ahead and put the actual code for GetMyTime into a new source file called MYTIME.C:

#include <time.h>

#include "mytime.h" int GetMyTime(int which)

{ struct tm time t

*timeptr; secsnow; time(&secsnow); timeptr

= localtime(&secsnow); switch (which) { case HOUR: return (timeptr -> tm_hour); case MINUTE: return (timeptr -> tm_min); case SECOND: return (timeptr -> t~sec);

MYTIME includes the standard header file time.h, which contains the prototype of the time and localtime functions, and the

Borland

C++

User's Guide

definition of tm and time_t, among other things. It also includes mytime.h in order to define HOUR, MINUTE, and SECOND.

Create these new files, then use Project I Open Project to open

MYPROG.PR}. The files MYMAIN.C and MYFUNCS.C are still in the Project window. Now to build your expanded project, you add the file name MYTIME.C to the Project window. Press

Ins

(or choose Project I

Add

Item) to bring up the Add Item dialog box. If you placed MYTIME.C in the current directory, use the Files list box to choose it now. If MYTIME.C is in a different directory, tab to the Name input box and type in MYTIME.C and its path. Once you've used either of these methods, press

Enter

to actually add the file. The Add button is the default action button.

Now press

F9to

make the project. MYMAIN.C will be recompiled because you've made changes to it since you last compiled it.

MYFUNCS.C won't be recompiled, because you haven't made any changes to it since the make in the earlier example.

MYTIME.C will be compiled for the first time.

In the MYPROG project window, move to MYMAIN.C, and press

Spacebar

(or Project I Include Files) to display the Include Files dialog box. This dialog box contains the name of the selected file, several buttons, and a list of include files and locations (paths).

The first file in the Include Files list box is highlighted; the list box lists all the files that were included by the file MYMAIN.C. If any of the include files is located outside of the current directory, the path to the file is shown in the Location field of the list box.

As each source file is compiled, the information about which include files are included by which source files is stored in the source file's

.OB}

file. If you access the Include Files dialog box before you perform a make, it might contain no files or it might have filesJeft over from a previous compile (which may be out of date). To load one of the include files into an Edit window, highlight the file you want and press

Enter

(or click on View).

Looking at files in a project

Let's take a look at MYMAIN.C, one of the files in the Project.

Simply choose the file using the arrow keys or the mouse, then press

Enter.

This brings up an edit window with MYMAIN.C loaded. Now you can make changes to the file, scroll through it, search for text, or whatever else you need to do. When you are finished with the file, save your changes if any

(F2),

then press

Alt-

to close the Edit window.

Chapter

Managing multi-file projects

143

144

Suppose that after browsing around in MYMAIN.C, you realize that what you really wanted to do was look at mytime.h, one of the files that MYMAIN.C includes. Highlight MYMAIN.C in the

Project window, then press

Spacebar

to bring up the Include Files dialog box for MYMAIN. (Alternatively, while MYMAIN.C is the active Edit window, select Project I Include Items or

Alt-P I.)

Now choose mytime.h in the Include Files box and press the View button. This brings up an Edit window with mytime.h loaded.

When you're done, press

Alt-F3

to close the mytime.h Edit window.

Notes for your project

Now that you've had a chance to see the code in MYMAIN.C and mytime.h, you've decided you'll optimize it as soon as you can.

Choose Window I Project Notes. This brings up a new Edit window that is kept as part of your project file. Type in the following:

Change History:

Chuck G.

Added check for out of memory in DBADDFIELD.

Harry B.

Fixed bug 0183.

Each project maintains its own notes file, so that you can keep notes that go with the project you're currently working on; they're at the touch of a button as soon as you select the project file. Press

Alt-F3

now to close the Project Notes Edit window.

Borland

C++

User's Guide

H A p

T E R

The editor from

A to Z

You might want to read this chapter even if you are familiar with the editor in other Borland language products. The Programmer's

Platform (the IDE) includes improvements to the editor.

Context-sensitive help is always just

keystroke away

(Ft).

This chapter is a reference to the IDE's full range of editing commands. Table 5.1 contains a list of all of the editor commands; the tables and text that follow it cover those aspects of the editor that need further explanation.

Remember, this chapter is concerned

just

with the editor. For an in-depth discussion of the Programmer's Platform as a whole, refer to Chapter 1. For a detailed reference to each menu and option, see Chpater 2.

The new and the old

You can still use Borland's familiar hot key combinations to move around your file, insert, copy, and delete text, and search and replace. However, you now have two brand-new menus on the menu bar: the Edit menu and the Search menu. In addition, you can use a mouse to accomplish many of the cursor movement and block-marking key commands.

The Edit menu contains commands for cutting, copying, and pasting in a file, cupying examples from Help to an Edit Window, and viewing the Clipboard. When you first start the IDE, an Edit window is already active. To open other Edit windows, go to the

File menu and choose Open. From an Edit window, you still press

F10

to get to the menu bar; to return to the Edit window, keep

145

Chapter

The editor from

pressing

Esc

until you are out of the menus.

If you have a mouse, you can also just click anywhere in the Edit window.

. . . As always, you enter text pretty much as if you were using a typewriter. To end a line, press

Enter.

When you've entered enough lines to fill the screen, the top line scrolls off the screen. Don't worry, it isn't lost, and you can move back and forth in your text with the scrolling commands that are described later.

If you want to undo some changes, you can use the Undo command, described in detail on page 34 in Chapter 2.

Editor reference

Table

5.7

summarizes aI/ editor commands.

The editor is much more powerful than the quick tutorial can show. In addition to the menu choices, it uses approximately 50 commands to move the cursor around, page through text, find and replace strings, and so on. These commands can be grouped into four main categories:

• Cursor movement

• Insert and delete operations

• Block operations

• Miscellaneous editing operations

Most of these commands need no explanation. Those that do are described in the text followmg Table 5.1.

Table 5.1

Full summary of editor commands

Movement Command

word is defined as a

sequence of characters

separated by one of the following: space

< > , :

. ( ) ( ) " ' * + - / $

# _ = I - ? ! " % & :

@ \,

and all control and graphic characters.

Cursor movement commands

Basic cursor movement

Character left

Character right

Word left

Word right

Lineup

Line down

Scroll up one line

Scroll down one line

Page up

Page down

Ctrl~

Ctr/~ l'

Ctrl-W

Ctrl-Z

PgUp

PgDn

146

Borland C++ User's Guide

ID.L

Many of the commands in this table can a/so be performed with the mouse. See Chapter 2.

Table 5.1: Full summary of editor commands (continued)

Movement Command

Long distance

Beginning of line

End of line

Top of window

Bottom of window

Beginning of file

End of file

Beginning of block

End of block

Last cursor position

Home

End

Ctrl Home

Ctrl End

Ctrl PgUp

Ctrl PgDn

Ctrl-Q B

Ctrl-Q K

Ctrl-Q P

Insert and delete commands

Insert mode on/off

Delete character left of cursor

Delete character at cursor

Delete word right

Insert line

Delete line

Delete to end of line

Options I Environment I Editor or

Ins

Backspace

Del

Ctrl-T

Clr/-N

Clrl-Y

Ctrl-Q Y

Block commands

Mark block

Mark single word

Copy block

Move block

Delete block

Read block from disk

Write block to disk

Hide/ display block

Print block

Indent block

Unindent block

Other editing commands

Autoindent on/off

Control character prefix**

Find place marker

Go to menu bar

New file

Open file

Optimal fill mode on/off

Pair matching

Print file

Quit IDE

Repeat last search

Restore error message

Shift..L.,

Clrl-KT

-7, f-,

Clrl-K B, Ctrl-K K

Edit

Copy, Edit

Paste or

Ctrl-Ins, Shift-Ins

Edit

Cut, Edit

Paste or

Shift-Del, Shift-Ins

Edit I Clear or

Cirl-Del

Ctrl-K R

Ctrl-K

Ctrl-K H

File I Print or

Ctrl-K P

Cirl-K I

Clr/-K U

Options I Environment I Editor*

Ctrl-P

Ctrl-Q n***

F10

File I New

File I Open

(F3)

Options

Environment

Editor*

Ctrl-Q

[and

Ctrl-Q J

File I Print

File I Quit

(Alt-X)

Search I Search Again or

Ctr/-L

Ctrl-Q W

Chapter 5, The editor from A to Z

147

Table 5.1: Full summary of editor commands (continued)

Movement Command

Undo changes

Return to editor from menus

Save

Search and replace

Set place marker

Tab

Tab mode

Unindent mode

Edit I Undo

Esc

FileISave(F2)

Search I Find or

Ctrl-Q F

Search I Replace or

Ctrl-Q A

Ctrl-K rt**

Tab

Options I Environment I Editor*

*This command opens the Environment Options dialog box, in which you can set the appropriate check box or radio buttons.

**Enter control characters by first pressing

Gtrl-P,

then pressing the desired control character. Depending on your screen setup, control characters appear as lowintensity or inverse capital letters.

***n

represents a number from 0 to 9.

Jumping around

There are three cursor movement commands that need further explanation:

Ctrl-Q B

and

Ctrl-Q K

move the cursor to the block-begin or blockend marker. Both these commands work even if the block is not displayed (see "Hide/ display block" in Table 5.2).

Ctrl-Q B

works even if the block-end marker is not set, and

Ctrl-Q K

works even if the block-begin marker is not set.

Beginning of block

End of block

Ctrl-Q B

Ctrl-Q K

Last cursor position

Ctrl-Q P

moves to the last position of the cursor before the last command. This command is particularly useful after a search or search-and-replace operation has been executed, and you'd like to return to where you were at before you ran the search.

Block commands

A block of text is any amount of text, from a single character to hundreds of lines, that has been surrounded with special blockmarker characters. There can be only one block in a window at a time. A block is marked by placing a block-begin marker on the first character and a block-end marker after the last character of

148

Borland

C++

User's Guide

the desired portion of the text. Once marked, the block can be copied, moved, deleted, printed, or written to a file.

Table 5.2: Block commands In depth

Movement Command(s) Function

Mark block

Mark single

Copy block

Move block

Delete block

Write block to disk

Read block from disk

Hide/ display block

Print block

Shift

J-, i, ~,

etrl-K T

Marks (highlights) a block as the cursor is moved. Marked text is displayed in a different intensity.

Marks a single word as a block. If the cursor is placed within a word, that word will be marked. If it is not within a word, then the word to the left of the cursor will be marked.

Edit I Copy,

Edit I Paste,

etrl-Ins

Shift-Ins

Copies a previously marked block to the Clipboard and pastes it to the current cursor position. The original block is unchanged, and the block markers are placed around the new copy of the block. If no block is marked or the cursor is within the marked block, nothing happens.

Edit I Cut, Shift-Del Moves a previously marked block from its original position to the

Edit I Paste, Shift-Ins Clipboard and pastes it to the cursor position. The block disappears from its original position; the markers remain around the block at its new position. If no block is marked, nothing happens.

Edit I Clear,

etrl-Del etrl-KY etrl-KW

Ctrl-K R etrl-K H etrl-K P

File I Print

Deletes a previously marked block. No provision exists to restore a deleted block, so be careful with this command.

Writes a previously marked block to a file. The block is left unchanged, and the markers remain in place. When you give this command, you are prompted for the name of the file to write to.

The file can be given any legal name (the default extension is .C).

If you prefer to use a file name without an extension, append a period to the end of its name.

Note:

You can use wildcards to select a file to overwrite; a directory is displayed. If the file specified already exists, a warning is issued before the existing file is overwritten. If no block is marked, nothing happens.

Reads a disk file into the current text at the cursor position, exactly as if it were a block. The text read is then marked as a block. When this command is issued, you are prompted for the name of the file to read. You can use wildcards to select a file to read; a directory is displayed. The file specified can be any legal filename.

Causes the visual marking of a block to be alternately switched off and on. The block manipulation commands (copy, move, delete, print, and write to a file) work only when the block is displayed.

Block-related cursor movements Gump to beginning/ end of block) work whether the block is hidden or displayed.

Sends the marked block in the active Edit window to the printer.

Sends the entire file in the active Edit window to the printer.

Chapter 5, The editor from A to Z

149

Other editing commands

The next table describes certain editing commands in more detail.

The table is arranged alphabetically by the name of the command.

Table 5.3: Other editor commands in depth

Movement Command(s) Function

Autoindent

Find place marker

New file

Options I

Environment I

Editor

Gtrl-Q n

Opens the Editor Options dialog box, in which you can toggle the

Autoindent Mode check box. Provides automatic indenting of successive lines. When Autoindent is active, the indentation of the current line is repeated on each following line; that is, when you press

Enter,

the cursor does not return to column one but to the starting column of the preceding non-empty line. When you want to change the indentation, use the

Spacebar

and f key to select the new column.

Autoindent is on by default.

Finds up to ten place markers

can be any number in the range 0 to 9) in text. Move the cursor to any previously set marker by pressing

Gtrl-Q

and the marker number.

Opens a new window.

Open file

Quit edit

FileIOpen(F3)

File I Quit

(Alt-X)

Lets you load an existing file into an Edit window.

Quits Borland c++.

You are asked whether you want to save the file to disk.

Undo changes Edit I Undo

Save file FileISave(F2)

Lets you undo editing changes.

Set place

Tab

Gtrl-K n

Tab

Saves the file and returns to the editor.

Mark up to ten places in text by pressing

Gtrl-K,

followed by a single marker digit (0 to 9). After marking your location, you can work elsewhere in the file and then easily return to your marked location by using the

Gtrl-Q N

command (being sure to use the same marker number). You can have ten places marked in each window.

Tabs default to eight columns apart in the Borland c++ editor.

Tab mode

File I New

Options I

Environment I

Opens the Editor Options dialog box, in which you can set the Use Tab

Character check box. When the option is on, you can insert tab characters (ASCII character 9); when it's off, the tab is automatically inserted as the correct number of spaces.

Editor

150

Borland

C++

User's Guide

Search and replace

The Search I Find and Search I Replace commands let you search for (and optionally replace) strings of up to 30 characters.

The search string is a/so called the target string.

The search string can contain any characters, including control characters. You can enter control characters with the

Gtrl-P

prefix. For example, enter a

Gtrl· Tby

holding down the

GIrl

key as you press

and then T. You can include a line break in a search string by specifying

Gfrl-M

(carriage return).

(For searching regular expressions, take a look at the text file about GREP.)

The following sections list the steps for performing these operations.

Searching and searching again

1. Choose Search I Find. This opens the Find dialog box.

2. Type the string you are looking for (up to 30 letters) into the Text to Find input box.

3. You can also set various search options: a The Direction radio buttons control whether you do a forward or backward search .

• The Scope radio buttons control how much of the file you search .

• The Origin radio buttons control where the search begins.

The Options check boxes determine whether the search will be case sensitive for whole words only, and for regular expressions.

Use

Tab

or your mouse to cycle through the options. Use

i

and -!, to set the radio buttons and

Space

to toggle the check boxes.

4. Finally, choose the OK button to carry out the search or the Cancel button to cancel. Borland c++ performs the operation.

5. If you want to search for the same item repeatedly, use

Search I Search Again.

Chapter 5, The editor from A to Z 151

152

Search and replace 1. Choose Search I Replace. This opens the Replace dialog box.

2. Type the string you are looking for (up to 30 letters) into the Text to Find input box.

3. Press

Tab

or use your mouse to move to the New Text input box. Type in the replacement string.

4. You can then set the same search options as in the Find dialog box.

5. Finally, choose OK or Change All to begin the search, or choose Cancel to cancel. Borland C++ performs the operation. Choosing Change All will replace every occurrence found.

If you want to stop the operation, press

Esc

at any point when the search has paused.

Pair matching

There you are, debugging your source file that is full of functions, parenthesized expressions, nested comments, and a whole slew of other constructs that use delimiter pairs. In fact, your file is riddled with

• braces: { and}

• angle brackets: < and>

• parentheses: ( and )

• brackets: [ and ]

• comment markers:

/* and

* /

• double quotes: "

• single quotes: '

Finding the match to a particular paired construct can be tricky. Suppose you have a complicated expression with a number of nested expressions, and you want to make sure all the parentheses are properly balanced. Or say you're at the beginning of a function that stretches over several screens, and you want to jump to the end of that function.

With Borland C++'s handy pair-matching commands, the solution is at your fingertips. Here's what you do:

Borland

C++

User's Guide

1. Place the cursor on the delimiter in question (for example, the opening brace of some function that stretches for a couple of screens).

2. To locate the mate to this selected delimiter, simply press

Ctrl-Q [. (In the example given, the mate should be at the end of the function.)

3. The editor immediately moves the cursor to the delimiter that matches the one you selected.

If it moves to the one you had intended to be the mate, you know that the intervening code contains no unmatched delimiters of that type. If it moves to the wrong delimiter, you know there's trouble in River City; now all you need to do is track down the source of the problem.

We've told you the basics of Borland C++'s "Match Pair" commands; now you need some details about what you can and can't do with these commands, and notes about a few subtleties to keep in mind. This section covers the following points:

III

There are actually two match pair editing commands: one for forward matching (Ctrl-Q [) and the other for backward matching

(Ctrl-Q

J) .

• The way the editor searches for comment delimiters (/* and

is slightly different from the way it performs the other searches .

• If there is no mate for the delimiter you've selected, the editor doesn't move the cursor.

Directional and nondirectional matching

Opening braces and brackets and closing braces and parentheses are directional; the editor knows which way to search for the mate, so It doesn't matter which match pair command you give.

Two match pair commands are necessary because some delimiters are

nondirectional.

For example, suppose you tell the editor to find the match for an opening brace ( { ) or an opening bracket ( [ ). The editor knows the matching delimiter can't be located

before

the one you've selected, so it searches forward for a match. If you tell the editor to find the mate to a closing brace (} ) or a closing parenthesis ( ) ), it knows that the mate can't be located

after

the selected delimiter, so it automatically searches backward for a match.

However, if you tell the editor to find the match for a double quote ( " ) or a single quote ( , ), it doesn't know automatically which way to go. You must specify the search

Chapter

The editor from

Z 153

154

Double and single quotes are not directional. You must specify the correct match pair command.

direction by giving the correct match pair command. If you give the command

Gtrl-Q Gtrl-!,

the editor searches forward for the match; if you give the command

Gtrl-Q Gtrl-],

it searches backward for the match.

The following table summarizes the delimiter pairs, whether they imply search direction, and whether they are nestable:

Table 5.4

Delimiter pairs

Nestable delimiters are explained after this table.

Delimiter pair

{

(

[

< >

1* *1

Direction implied?

Yes

Are they nestable?

Yes

Yes and

Nestable delimiters

Nestable

means that, when the editor is searching for the mate to a directional delimiter, it keeps track of how many delimiter levels it enters and exits during the search.

This is best illustrated with some examples:

Figure 5.'

Search for match to square bracket or parenthesis matched pair

~ arrl [arr2 [x] ]

T matched pair matched pair matched pair

0) && (y

0) matched pair

Comment delimiters

Because comment delliniters are two-character delliniters, you must take care when you highlight one for a match pair search. In either case, the editor recognizes only the

first

of the two characters: the slash (/) part of a

/* comment delimiter, or the asterisk (*) part of a * / delimiter. If you place the cursor on the

second

character in either of these

Bor/and

c++

User's Guide

The search will

affected if unmatched delimiters of the same type in comments, quotes, or conditional compilation sections fall between the matched pair.

delimiters, the editor won't know what you're looking for, so it won't do any searching at all.

Also, as shown in Table 5.4, comment delimiters are sometimes nestable, sometimes not ("Yes and No"). This is not a vagary or an inability to decide: It is a test dependent on multiple conditions. ANSI-compatible C programs cannot contain nested comments, but Borland C++ provides an optional nested comments feature that you can set to on or off. This feature affects the nestability of comment delimiters when it comes to pair matching.

• If

Nested Comments is checked, the editor treats comment delimiters as nestable and keeps track of the delimiter levels it enters and exits in the search for a match.

• If

Nested Comments is unchecked, the editor won't treat comment delimiters as nestable; when a selected, the first

/* pair is

* /

pair the editor finds is the match (and vice versa).

To set Nested Comments, choose Options I Compiler I

Source. This opens the Source Options dialog box; use

Spacebar

to set the Nested Comments check box, then choose the OK button to confirm the setting.

Here are some examples to illustrate these differences. In the first two examples, the search is performed with

Ctrl-Q [.

Figure 5.2, Nested Comments is checked. In Figure 5.3,

Nested Comments is unchecked. In the third example, a backward search is performed using

Ctrl-Q

Comments still unchecked.

Figure 5.2

Forward search I

/* /* /* /* Here are some nested comments. */ */ */ *(

I match level selected match level - - - - - ' . found

Note

A backward search from the found

* /

will yield the selected

/* when Nested Comments is checked.

Figure 5.3

Forward search II

/* /* /* /* Here are some nested comments.

I match level selected match level found

*/ */ */

Chapter

The editor from

155

Figure 5.4

Backward search

/* /* /* /*

I

Here are some nested comments. */ */ */ */ match level match level selected found

I

156

Bor/and

C++

User's Guide

A p

T E R

The command-line compiler

The command-line compiler lets you invoke 0/1 the

functions of the IDE compiler

from the DOS command line.

As an alternative to using the IDE, you can compile and run your programs with the command-line interface, hereafter referred to as the command-line compiler. The command-line compiler does more than just compile your files. It is in effect a command-line version of the IDE. Almost anything you can do within the IDE can also be done using the command-line compiler. You can set warnings on or off, use EMS or not, run in real or protected mode, invoke TASM (or another assembler) to assemble .ASM source files, and so on. In fact, to

compile only

you have to use the

-c

option at the command line.

This chapter is organized into two parts. The first describes how to use the command-line compiler and provides a summary table of all the options. The second part, starting on page 165, presents the options organized functionally (with groups of related options).

The summary table, Table 6.1 (starting on page 160), summarizes the command-line compiler options and provides a page-number cross-reference to where you can find more detailed information about each option. The options are also indexed individually so you can find discussions relating to them in other chapters and other books in the Borland C++ manuals.

Chapter

The command-line compiler

157

Using the command-line compiler

You can run the command-line compiler in either real or protected mode. You can use protected mode if you have a 286, 386, or i486 machine with at least 640K conventional RAM and at least

576K extended or simulated expanded memory; most of the time you'll probably prefer to use it. Otherwise, use real mode.

Note that, although you may be running Borland C++ in protected mode, you are still generating applications to run in real mode. The greatest advantage to using Borland C++ in protected mode is that the compiler has

much

more room to run than if you were running it in real mode, while your application has more real-mode memory.

Running in real mode

You can a/so use

configuration file. See page

764

for details.

To invoke Borland c++ from the command line in real mode, type

Bee at the DOS prompt and follow it with a set of command-line arguments. Command-line arguments include compiler and linker options and file names. The generic command-line format is

BCC

[option [option ... ]]filename [filename ... ]

With two exceptions, each command-line option is preceded by a hyphen (-) and is separated from the BCC command, other options, and following file names by at least one space.

Running in protected mode

Running Borland C++ in protected mode involves interaction between three files: BCCX.EXE, BCCX.OVY, and TKERNEL.EXE.

BCCX.EXE loads TKERNEL and BCCX.OVY, which is the protected-mode version of the command-line compiler. Although

BCCX.EXE loads these files automatically, so that you don't need to be concerned with invoking them yourself, they do both need to be on the path or in the BCCX.EXE startup directory so it can find them.

Once you've verified that the paths are set correctly, running

Borland c++ in protected mode is as simple as running it in real mode; the syntax is identical except for using BCCX in the place of

BCC:

158

Borland

C++

User's Guide

BCCX

[option [option ... ]] filename [filename ... ]

The options and file names are identical to those for BCC; therefore, for the remainder of this chapter, when we mention the command-line compiler we mean both BCC and BCCX (unless we specifically state otherwise).

. . BCCX.EXE loads TKERNEL each time you invoke BCCX. You can save a great deal of loading time by preloading TKERNEL; before running BCCX, type

TKERNEL hi==yes on the DOS command line. When you are through with your

Borland C++ session, type

TKERNEL rem to remove TKERNEL.

If you are using the command-line compiler in conjunction with

Windows, you'll need to type

TKERNEL hi==yes kilos==1024 and invoke Windows using the

(standard mode) option.

Using the options

Compiler options are further divided into ten groups.

The options are divided into three general types:

• compiler options, described starting on page 165

Blinker options, described starting on page 183

• environment options, described starting on page 183

To see an onscreen list of the options, type

Bee or

Beex

(without any options or file names) at the DOS prompt. Then press

Enter.

Use this feature to override settings in configuration files.

In order to select command-line options, enter a hyphen (-) immediately followed by the option letter (for example, -I). To turn an option off, add a second hyphen after the option letter.

This is true for all toggle options (those that turn an option on or off): A trailing hyphen (-) turns the option off, and a trailing plus sign (+) or nothing turns it on. So, for example, -C and -C+ both turn nested comments on, while -C- turns nested comments off.

Chapter

The command-line compiler

159

Option precedence rules

The option precedence rules are simple; command-line options are evaluated from left to right, and the following rules apply:

• For any option that is

not

-lor -L

option, a duplication on the right overrides the same option on the left. (Thus an

off

option on the right cancels an

on

option to the left.)

• The

-I and -L

options on the left, however, take precedence over those on the right.

Table 6.1: Command-line options summary

Option

@filename

+filename

-1

-1-

-2

-A

-A-,-AT

-AK

-AU

-a

-a-

-B

-b

-b-

-C

-C-

-c

-Dname

-Dname=string

-d

-d-

-Efilename

-efilename

-Fc

-Ff

-Ff=size

-Fm

-Fs

-f

-f-

-£f

-£f-

-f87

-f287

168

178

183

168

174

178

167

168

169

167

174

167

178

168

Page

163

164

Function

Gives the command-line compiler a response file name

Tell the command-line compiler to use the alternate configuration file

filename

Generate 80186 instructions

Generate 8088/8086 instructions

Generate 80286 protected-mode compatible instructions

Use only ANSI keywords

Use Borland C++ keywords (default)

Use only Kernighan and Ritchie keywords

Use only UNIX keywords

Align word

Align byte (default)

Compile and call the assembler to process inline assembly code

Make enums word-sized (default)

Make enums signed or unsigned

Nested comments on

Nested comments off (default)

Compile to

.OBI

but do not link

Define

name

to the string consisting of the null character

Defines

name

string

Merge duplicate strings on

Merge duplicate strings off (default)

Use

filename

as the assembler to use

Link to produce

filename.EXE

Generates COMDEFs

Creates far variables automatically

Creates far variables automatically; sets the threshold

Enables the -Fc, -Ff, and

-Fs

options

Assume DS

SS in all memory models

Emulate floating point (default)

Don't do floating point

Fast floating point (default)

Strict ANSI floating point

Use 8087 hardware instructions

Use 80287 hardware instructions

160

Borland

C++

User's Guide

-jn

-K

-K-

-k

-Lpath

-Ix

-l-x

-M

-mc

-mh

-ml

-mm

-G

-G-

-gn

-H

-H-

-Hu

-H=filename

-h

-Ipath

-in

-mm!

-ms

-ms!

-mt

-mt!

-N

-npath

-0

-0-

-ofilename

-P

-Pext

-P-

-P-ext

Table 6.1: Command-line options summary (continued)

Option Page Function

170

184

183

166

172

174

178

169

184

174

175

170

166

170

184

172

179

-p

-p-

-Qe

-Qe-

-Qx

-Qx=nnnn

-Qx=nnnn,yyyy

-Qx=,yyyy

-Qx-

170

180

181

Optimize for speed

Optimize for size (default)

Warnings: stop after n messages

Causes the compiler to generate and use precompiled headers

Turns off generation and use of precompiled headers (default)

Tells the compiler to use but not generate precompiled headers

Sets the name of the file for precompiled headers

Use fast huge pointer arithmetic

Directories for include files

Make significant identifier length to be n

Errors: stop after n messages

Default character type

unsigned

Default character type

signed

(default)

Standard stack frame on (default)

Directories for libraries

Pass option

to the linker (can use more than one

Suppress option

for the linker

Instruct the linker to create a map file

Compile using compact memory model

Compile using huge memory model

Compile using large memory model

Compile using medium memory model

Compile using medium model; assume DS != SS

Compile using small memory model (default)

Compile using small model; assume DS != SS

Compile using tiny memory model

Compile using tiny model; assume DS != SS

Check for stack overflow

Set the output directory

Optimize jumps

No optimization (default)

Compile source file to filename.obj

Perform a C++ compile regardless of source file extension

Perform a C++ compile and set the default extension to ext

Perform a C++ or C compile depending on source file extension (default)

Perform a C++ or C compile depending on extension; set default extension to ext

Use Pascal calling convention

Use C calling convention (default)

Instructs the compiler to use all available EMS memory (default)

Instructs the compiler to not use any EMS memory

Instructs the compiler to use all available extended memory

Instructs the compiler to reserve nnnn Kbytes of extended memory for other programs, and to use the rest itself

Instructs the compiler to reserve nnnn Kbytes of extended memory for other programs and yyyy for itself

Instructs the compiler to reserve yyyy Kbytes of extended memory for itself

Instructs the compiler to not use any extended memory

Chapter

The command-line compiler

161

-WE

-WS

-w

-wxxx

-w-xxx

-X

-y

-Yo

-y

-z

-zAname

-zBname

-zCname

-zDname

-zEname

-zFname

-zGname

-zHname

-zPname

-zRname

-zSname

-zTname

-zX*

Table 6.1: Command-line options summary (continued)

Option Page Function

-r

-r-

-rd

-S

-Tstring

-T-

-Una me

-u

-u-

-V

-Vs

-VO,-V1

-Vf

-v,-v-

-vi,-vi-

-W

-WD

-WDE

171

173

177

180

175

171

177

178

172

173

179

167

170

182

171

172

179

180

Use register variables on (default)

Suppresses the use of register variables.

Only allow declared register variables to be kept in registers

Produce .ASM output file

Pass

string

as an option to TASM or assembler specified with

-E

Remove all previous assembler options

Undefine any previous definitions of

name

Generate underscores (default)

Disables underscores

Smart C++ virtual tables

Local C++ virtual tables

External and Public C++ virtual tables

Far C++ virtual tables

Source debugging on

Controls expansion of inline functions

Creates an

.OBI

for Windows with all functions exportable

Creates an

.OBI

for Windows to be linked as a .DLL with all functions exportable

Creates an

.OBI

for Windows to be linked as a .DLL with explicit export functions

Creates an

.OBI

for Windows with explicit export functions

Creates an

.OBI

for Windows that uses smart callbacks

Display warnings on

Enable

xxx

warning message

Disable

xxx

warning message

Disable compiler autodependency output

Enable overlay code generation

Overlay the compiled files

Line numbers on

Enable register usage optimization

Code class

BSS class

Code segment

BSSsegment

Far segment

Far class

BSSgroup

Far group

Code group

Data segment

Data group

Data class

Use default name for X. (default)

162

Borland

C++

User's Guide

Syntax and file names

Borland C++ compiles files according to the following set of rules:

c++ files have the extension

.CPP; see page

779

for information on changing the default extension.

filename.asm Invoke TASM to assemble to .OB} filename.obj Include as object at link time filename. lib Include as library at link time filename Compile FILENAME.CPP filename.cpp Compile FILENAME.CPP filename.c Compile FILENAME.C filename.xyz Compile FILENAME.XYZ

For example, given the following command line

BCC -a -f

-c

-0

-z

-emyexe oldfilel oldfile2 next file

Borland C++ compiles OLDFILE1.CPP, OLDFILE2.CPP, and

NEXTFILE.CPP to an .OBJ,linking them to produce an executable program file named MYEXE.EXE with word alignment (-a), floating-point emulation (-f), nested comments (-C), optimization

(-0), and register usage optimization (-Z) selected.

Borland C++ invokes TASM if you give it an .ASM file on the command line or if a .C or .CPP file contains inline assembly. The options that the command-line compiler gives to T ASM are

/D MODEL /D lang

/m!

/floatopt

where

MODEL

is one of: TINY, SMALL, MEDIUM, COMPACT,

LARGE, or HUGE. The

Iml

option tells TASM to assemble with case sensitivity on.

lang

is CDECL or PASCAL;

floatopt

r

when you've specified -f87 or -f287;

e

otherwise.

Response files

Response fifes allow you to have longer command strings than DOS normally allows.

If you need to specify many options and/or files on the command line, you can place them in an ASCII text file, called a response file

(you can of course name it anything you like). You can then tell the command-line compiler to read its command line from this file by including the appropriate file name prefixed with

You can specify any number of such files, and you can mix them freely with other options and/or file names.

For example, suppose the file MOON.RSP contains STARS.C and

RAIN.C. This command

BCC SUN.C @MOON.RSP ANYONE.C

Chapter

The command-line compiler

163

will cause Borland c++ to compile the files SUN.C, ST ARS.C,

RAIN.C, and ANYONE.C in real mode.

It expands to

BCC SUN.C STARS.C RAIN.C ANYONE.C

Any options included in a response file are evaluated just as though they had been typed in on the command line. See page

160 for what those rules are.

Configuration files

TURBOC.CFG is not the same as TCCONFIG. TC, which Is the default IDE version of

configuration file.

If you find you use a certain set of options over and over again, you can list them in a configuration file, called TURBOC.CFG by default. If you have a TURBOC.CFG configuration file, you don't need to worry about using it.

When you run BCC (or BCCX), it automatically looks for TURBOC.CFG in the current directory. If it doesn't find it there

and

if you're running DOS 3.x or higher,

Borland C++ then looks in the startup directory (where BCC.EXE or BCCX.EXE resides).

You can create more than one configuration file; each must have a unique name. To specify the alternate configuration file name, include its file name, prefixed with

+, anywhere on the BCC (or

BCCX) command line. For example, to read the option settings from the file D: \ALT.CFG, you could use the following command line:

BCC +D:\ALT.CFG ..... .

Your configuration file can be used in addition to or instead of options entered on the command line. If you don't want to use certain options that are listed in your configuration file, you can override them with options on the command line.

You can create the TURBOC.CFG file (or any alternate configuration file) using any standard ASCII editor or word processor, such as Borland C++'s integrated editor. You can list options (separated by spaces) on the same line or list them on separate lines.

Option precedence rules

In general, you can just remember that options given on the command line override the same options specified in the configuration file. This ability to override configuration file options with command-line options is an important one. If, for example, your configuration file contains several options, including the

-a option (which you want to turn

ofj),

you can still use the configuration file but override the -a option by listing -ain the command line. However, the rules are a little more detailed than that. The

164

Borland

C++ User's Guide

option precedence rules detailed on page 160 apply, with these additional rules:

1. When the options from the configuration file are combined with the command-line options, any

-I and -L options in the

configuration file are appended to the right of the commandline options. This means that the include and library directories specified in the command line are the first ones that

Borland C++ searches (thereby giving the

command-line-I

and

-L

directories priority over those in the configuration file).

2. The remaining configuration file options are inserted immediately after the BCC (or BCCX) command (to the left of any command-line options). This gives the command-line options priority over the configuration file options.

Compiler options

See page

166.

See page

167.

See page

167.

See page

172.

See page

173.

See page

174.

See page

177.

Borland C++'s command-line compiler options fall into ten groups; the page references to the left of each group tell where you can find a discussion of each kind of option:

Memory model options

let you tell Borland C++ which memory model to use when compiling your program.

Macro definitions

let you define and undefine macros on the command line.

Code generation options

govern characteristics of the generated code, such as the floating-point option, calling convention, character type, or CPU instructions.

Optimization options

let you specify how the object code is to be optimized; for size or speed, with or without the use of register variables, and with or without assumptions about aliases.

Source code options

cause the compiler to recognize (or ignore) certain features of the source code; implementationspecific (non-ANSI, non-Kernighan and Ritchie, and non-

UNIX) keywords, nested comments, and identifier lengths.

Error-reporting options

let you tailor which warning messages the compiler will report, and the maximum number of warnings and errors that can occur before the compilation stops.

Segment-naming control options

allow you to rename segments and to reassign their groups and classes.

Chapter

The command-line compiler

165

See page

778.

See page 780.

See page

782.

Compilation control options

let you direct the compiler to

• compile to assembly code (rather than to an object module)

• compile a source file that contains inline assembly (there are other ways though: use

#pragma inline

or just ignore it)

• compile without linking

• compile for Windows applications

• use precompiled headers or not

EMS and extended memory options

let you control how much expanded and extended memory Borland c++ uses.

10.

C++ virtual table options

let you control how virtual tables are handled.

Memory model

Memory model options let you tell Borland c++ which memory model to use when compiling your program. The memory models are: tiny, small, medium, compact, large, and huge.

See Chapter

in the Programmer's Guide for indepth information on the memory models (what they are, how to use them).

-me Compile using compact memory model

-mh

Compile using huge memory model

-ml

Compile using large memory model

-mm Compile using medium memory model

-mm!

Compile using medium model; D5

-ms

-ms!

-mt

-mt!

Compile using small memory model (the default)

Compile using small model; D5

Compile using tiny memory model

Compile using tiny model; DS

You can't use the

-N option

when using one of the OS 1=

SSmodels.

The net effect of the -mt!, -ms!, and -mm! options is actually very small.

If you take the address of a stack variable (auto or parameter), the default (when DS == 5S) is to make the resulting pointer a near (DS relative) pointer. In this way one can simply assign the address to a default sized pointer in those models without problems. When D5 != 55, the pointer type created when you take the address of a stack variable is an _ss pointer. This means that the pointer can be freely assigned or passed to a far pointer or to a

_ss pointer. But for the memory models affected, assigning the address to a near or default-sized pointer will produce a "Suspicious pointer conversion" warning. Such warnings are usually errors, and the warning defaults to on. You should regard this kind of warning as a likely error.

166

Borland

C++ User's Guide

Macro definitions

Macro definitions let you define and undefine macros (also called

manifest

symbolic

constants) on the command line. The default definition is the null string. Macros defined on the command line override those in your source file.

-Oname

Defines the named identifier

name

to the empty string.

-0

name= string

Defines the named identifier

name

to the string

string

after the equal sign.

string

cannot contain any spaces or tabs.

-Uname

Undefines any previous definitions of the named identifier

name.

Borland C++ lets you make multiple

#define

entries on the command line in any of the following ways:

You can include multiple entries after a single

-0

option, separating entries with a semicolon (this is known as "ganging" options):

BCC

-Dxxx;yyy=l;zzz=NO

MYFILE.C

• You can place more than one

-0

option on the command line:

BCC

-Dxxx -Dyyy=l

-Dzzz=NO MYFILE.C

• You can mix ganged and multiple -0 listings:

BCC

-Dxxx -Dyyy=l;zzz=NO

MYFILE.C

Code generation options

Code generation options govern characteristics of the generated code, such as the floating-point option, calling convention, character type, or CPU instructions.

-1

This option causes Borland C++ to generate extended

80186 instructions. It also generates 80286 programs running in real mode, such as with the IBM PCI AT under

DOS.

-1Tells the compiler to generate 8088/8086 instructions.

-2

This option causes Borland C++ to generate protected-mode compatible instructions.

80286

Chapter

The command-line compiler

167

168

-a

-b

-b-

-d

-Fc

-Ff

This option forces integer size and larger items to be aligned on a machine-word boundary. Extra bytes are inserted in a structure to ensure member alignment.

Automatic and global variables are aligned properly. char and unsigned char variables and fields can be placed at any address; all others are placed at an even-numbered address. This option is off by default (-a-), allowing bytewise alignment.

This option (which is on by default) tells the compiler to always allocate a whole word for enumeration types.

(This is the way Turbo C 2.0 treats enumerations.)

This option tells the compiler to allocate an unsigned or signed byte if the minimum and maximum values of the enumeration are both within the range of 0 to 255 or -128 to 127, respectively.

This option tells the compiler to merge literal strings when one string matches another, thereby producing smaller programs. This option is off by default

(-d-).

This generates communal variables (COMDEFs) for global"C" variables that are not initialized and not declared as static or extern.

The advantage of using this option is that header files that are included in several source files can contain declarations of global variables.

So long as a given variable doesn't need to be initialized to a nonzero value, you don't need to include a definition for it in any of the source files. You can use this option when porting code that takes advantage of a similar feature with another implementation.

In the tiny, small, and medium models, the generated

COMDEFs will be near; in the compact, large, and huge models they will be far.

When you use this option, global variables greater than or equal to the threshold size are automatically made far by the compiler. The threshold size defaults to 32,767; you can change it with the

-Ff=size

option. This option is useful for code that doesn't use the huge memory model but declares enough large global variables that their total size exceeds (or is close to) 64K.

Borland

C++

User's Guide

-Ff= Use this option to change the threshold size used by the

size

-Ff option.

-Fm

-Fs

-f

-f-

-ff

This option enables all the other

-F options

(-Fe, -Ff and

-Fs). You can use it as a handy shortcut when porting code from other compilers.

This option tells the compiler to assume that DS is equal to SS in all memory models; you can use it when porting code originally written for an implementation that makes the stack part of the data segment. When you specify this option, the compiler will link in an alternate startup module (COFx.OBJ) that will place the stack in the data segment.

This option tells the compiler to emulate 80x87 calls at run time if the run-time system does not have an 80x87; if it does have one, the compiler calls the 80x87 chip for floating-point calculations (the default).

This option specifies that the program contains no floating-point calculations, so no floating-point libraries will be linked at the link step.

With this option, the compiler optimizes floating-point operations without regard to explicit or implicit type conversions. Answers can be faster than under ANSI operating mode. See Chapter 7, "Math," in the

Programmer's Guide

for details.

-ff-

This option turns off the fast floating-point option. The compiler follows strict ANSI rules regarding floatingpoint conversions.

-f87

This option tells the compiler to generate floating-point operations using inline 80x87 instructions rather than using calls to 80x87 emulation library routines. It specifies that a math coprocessor will be available at run time; therefore, programs compiled with this option will not run on a machine that does not have a math coprocessor.

-f287

This option is similar to -f87, but uses instructions that are only available with an 80287 (or higher) chip.

-h This option offers an alternative way of calculating huge pointer expressions; a way which is much faster but must be used with caution. When you use this option, huge

Chapter

The command-line compiler

169

170

-K

-k

-N

-p

pointers are normalized only when a segment wraparound occurs in the offset part. This will cause problems for huge arrays if any array elements cross a segment boundary. This option is off by default.

Normally, Borland c++ normalizes a huge pointer whenever adding to or subtracting from it. This ensures that, for example, if you have a huge array of

structs

that's larger than 64K, indexing into the array and selecting a

struct

field will always work with

structs

of any size. Borland c++ accomplishes this by always normalizing the results of huge pointer operations, so that the offset part contains a number that's no higher than 15.

That way, a segment wraparound never occurs with huge pointers. The disadvantage of this approach is that it tends to be quite expensive in terms of execution speed.

This option tells the compiler to treat all

char

declarations as if they were

unsigned char

type. This allows for compatibility with other compilers that treat

char

declarations as

unsigned.

By default,

char

declarations are

signed

(-K-).

This option generates a standard stack frame, which is useful when using a debugger to trace back through the stack of called subroutines. This option is on by default.

This option generates stack overflow logic at the entry of each function, which causes a stack overflow message to appear when a stack overflow is detected. This is costly in terms of both program size and speed but is provided as an option because stack overflows can be very difficult to detect.

If an overflow is detected, the message "Stack overflow!" is printed and the program exits with an exit code of 1.

This option forces the compiler to generate all subroutine calls and all functions using the Pascal parameter-passing sequence. The resulting function calls are smaller and faster. Functions must pass the correct number and type of arguments, unlike normal C use, which permits a variable number of function arguments. You can use the

cdecl

statement to override this option and specifically declare functions to be C-type. This option is off by default (-p-).

Bor/and c++

User's Guide

-u With -u selected, when you declare an identifier, Borland

C++ automatically puts an underscore ( _ ) in front of the identifier before saving the identifier in the object module.

Borland C++ treats Pascal-type identifiers (those modified by the pascal keyword) differently-they are uppercase and are

not

prefixed with an underscore.

Unless you are an expert, don't use

-u-.

See Chapter

9, "Interfacing with assembly

language, " in the Program-

mer's Guide for details about underscores.

Underscores for C and C++ identifiers are optional, but on by default. You can turn them off with -u-. However, if you are using the standard Borland c++ libraries, you will encounter problems unless you rebuild the libraries.

(To do this, you will need the Borland C++ run-time library source code; contact Borland for more information. )

Note that you cannot use this option if you are using any of the -W (Windows applications) options (and vice versa).

-x

-y

This option disables generation of autodependency information in the output file. Modules compiled with this option enabled will not be able to use the autodependency feature of MAKE or of the IDE. Normally this option is only used for files that are to be put into .LIB files (to save disk space).

-V

This option generates overlay-compatible code. Every file in an overlaid program must be compiled with this option; see Chapter 6, "Memory management," in the

Programmer's Guide

for details on overlays.

-Vo

This option overlays the compiled file(s); see Chapter 6 in the

Programmer's Guide

for details.

This option includes line numbers in the object file for use by a symbolic debugger, such as Turbo Debugger. This increases the size of the object file but doesn't affect size or speed of the executable program. This option is useful only in concert with a symbolic debugger that can use the information.

In general,

-y is more useful than

-y with

Turbo Debugger.

The -v and -vi options -y

Turbo Debugger is both

source level (symbolic) and assembly level debugger.

This option tells the compiler to include debugging information in the

.OBI

file so that the file(s) being compiled can be debugged with either Borland C++'s integrated debugger or the standalone Turbo Debugger. The compiler also passes this option on to the linker so it can include the debugging information in the .EXE file.

Chapter

The command-line compiler

171

172

-vi

To facilitate debugging, this option also causes c++ inline functions to be treated as normal functions.

If you want to avoid that, use -vi.

With this option enabled, c++ inline functions will be expanded inline.

In order to control the expansion of inline functions, the operation of the -v option is slightly different for c++.

When inline function expansion is not enabled, the function will be generated and called like any other function. Debugging in the presence of inline expansion can be extremely difficult, so we provide the following options:

-v This option turns debugging on and inline expansion off

-vThis option turns debugging off and inline expansion on

-vi

-vi-

This option turns inline expansion on

This option turns inline expansion off

So, for example, if you want to tum both debugging and inline expansion on, you must use -v -vi.

Optimization options

Optimization options let you specify how the object code is to be optimized; for size or speed, with or without the use of register variables, and with or without assumptions about aliases.

-G This option causes the compiler to bias its optimization in favor of speed over size.

-GThis option, the default, causes the compiler to bias its optimization in favor of size over speed (where smaller is better).

-0 This option eliminates redundant jumps (such as jumps to jumps) and multiple copies of identical code that jump to the same location.

It also suppresses redundant register loads. When -Z is not on, this will not change the behavior of your program (except, of course, that the code becomes more efficient).

-0When you disable optimizations, your code will compile very quickly but may be less efficient.

-r This option enables the use of register variables (the default).

Bor/and

C++

User's Guide

Unless you are an expert, don't use -r-.

-r-

-rd

Exercise caution when using this option. The compiler cannot detect if

register has been invalidated indirectly by

pointer.

-z

This option suppresses the use of register variables. When you are using this option, the compiler won't use register variables, and it won't preserve and respect register variables (SI,DI) from any caller. For that reason, you should not have code that uses register variables call code which has been compiled with -r-.

On the other hand, if you are interfacing with existing assembly-language code that does not preserve SI,DI, the

-roption allows you to call that code from Borland c++.

This option only allows declared register variables to be kept in registers.

This option allows the compiler to assume that variables are not accessed both directly and via a pointer in the same function.

It only has an effect when used with -0.

The compiler keeps a table that reflects the current contents of registers. If a variable had to be loaded from memory into a register, the compiler remembers that the register now contains a copy of the variable. If the variable is used again, the compiler uses the copy in the register rather than the value in memory.

The -Z option determines how the compiler handles indirect assignments (that is, assignments via pointers, or assignments via reference in C++). Normally it assumes that such assignments could potentially change any variable. Therefore it has to forget about all copies of variables in registers (that is, erase the table). -Z tells the compiler that indirect assignments will not change variables, and that it is therefore safe to retain the copies.

The bottom line is that if you access a variable both directly and via a pointer within the same function, setting -Z

can

generate wrong code and is therefore unsafe to use. On the other hand, it

will produce slightly faster code.

Source code options

Source code options cause the compiler to recognize (or ignore) certain features of the source code; implementation-specific (non-

ANSI, non-Kernighan and Ritchie, and non-UNIX) keywords,

Chapter

The command-line compiler

173

See Chapter

"Lexical

grammar, " in the Program-

mers Guide for

complete

list of the Borland C++

keywords,

nested comments, and identifier lengths. These options are most significant if you plan to port your code to other systems.

-A

This option compiles ANSI-compatible code: Any of the

Borland C++ extension keywords are ignored and can be used as normal identifiers. These keywords include asm cdecl

_cs

_ds

_es

_export far huge interrupt

_Ioadds near pascal

-A-

-AK

-AU

-C

-in and the register pseudovariables, such as _AX, _BX, _SI, and so on.

This option tells the compiler to use Borland C++ keywords. -AT is an alternate version of this option.

This option tells the compiler to use only Kernighan and

Ritchie keywords.

This option tells the compiler to use only UNIX keywords.

This option allows you to nest comments. Comments may not normally be nested.

This option causes the compiler to recognize only the first

n characters of identifiers. All identifiers, whether variables, preprocessor macro names, or structure member names, are treated as distinct only if their first

n

characters are distinct.

By default, Borland C++ uses 32 characters per identifier.

Other systems, including some UNIX compilers, ignore characters beyond the first eight.

If you are porting to these other environments, you may wish to compile your code with a smaller number of significant characters.

Compiling in this manner will help you see if there are any name conflicts in long identifiers when they are truncated to a shorter significant length.

Error-reporting options

Error-reporting options let you tailor which warning messages the compiler will report, and the maximum number of warnings and errors that can occur before the compilation stops.

174

Bor/and

c++

User's Guide

-gn

-jn

This option tells Borland c++ to stop compiling after

n

warning messages.

This option tells the compiler to stop compiling after

error messages.

-w This option causes the compiler to display warning messages. You can turn this off with -w-. You can enable or disable specific warning messages with

-wxxx,

described in the following paragraphs.

For more information on these warnings, see Chapter

70, "Error messages," in the

Programmer's Guide.

-wxxx

This option enables the specific warning message indicated by

xxx.

The option

-w-xxx

suppresses the warning message indicated by

xxx.

The possible options for

-wxxx

are listed here and divided into four categories: ANSI violations, frequent errors (including more frequent errors), portability warnings, and c++ warnings. You can also use the pragma warn in your source code to control these options. See Chapter 4,

"The preprocessor," in the

Programmer's Guide.

The asterisk

(*)

indicates that the option is on by default.

All others are off by default.

ANSI violations

-wbbf

-wbfs*

-wbig*

-wdcl*

-wdpu*

-wdup*

-weas

-wext*

-wpin

-wret*

-wstu*

-wsus*

-wvoi*

-wzdi*

Bit fields must be signed or unsigned into

Untyped bit field assumed signed into

Hexadecimal value contains more than three digits.

Declaration does not specify a tag or an identifier.

Declare

function

prior to use in prototype.

Redefinition of

macro

is not identical.

Assigning

integer _val

enumeration.

. Identifier

is declared as both external and static.

This initialization is only partially bracketed.

Both return and return with a value used.

Undefined structure

structure.

Suspicious pointer conversion.

Void functions may not return a value.

Division by zero.

Frequent errors

-wamb

-wamp

-wasc*

-wasm

-waus*

Ambiguous operators need parentheses.

Superfluous & with function or array.

Restarting compile using assembly.

Unknown assembler instruction.

Identifier

is assigned a value that is never used.

Chapter

The command-line compiler

175

176

-wdef

-weff*

-wfdt*

-will*

-wnod

-wpar*

-wpia*

-wpro

-wrch*

-wrvl*

-wstv

-wuse

Possible use of

identifier

before definition.

Code has no effect.

Function definition cannot be a typedef'd declaration.

Ill-formed pragma.

No declaration for

functionfunction.

Parameter

parameter

is never used.

Possibly incorrect assignment.

Call to function with no prototype.

Unreachable code.

Function should return a value.

Structure passed by value.

Identifier

declared but never used.

Portability warnings

-wcln

-wcpt*

-wrng*

-wrpt*

-wsig

-wucp

Constant is long.

Nonportable pointer comparison.

Constant out of range in comparison.

Nonportable pointer conversion.

Conversion may lose significant digits.

Mixing pointers to

signed

and

unsigned char.

c++ warnings

-watt*

-wbei*

-whid*

-winl*

-wlin*

-wlvc*

-wncf*

-wnci*

-wobi*

-wofp*

-womf*

-wovl*

-wscp*

Assignment to instead.

this

is obsolete; use

X::operator new

Initialization with inappropriate type.

Functionl

hides virtual function

function2.

Functions containing

identifier

are not expanded inline.

Temporary used to initialize

identifier.

Temporary used for parameter in call to

identifier.

Non-const function

function

called const object.

The constant member

identifier

is not initialized.

Base initialization without a class name is now obsolete.

This style of function definition is now obsolete.

Obsolete syntax; use :: instead.

Use of overload is now unnecessary and obsolete.

Identifier

is both a structure tag and a name; now obsolete.

Borland

C++

User's Guide

Segment-naming control

Don't use these options unless you have

good understanding of segmentation on the 8086 processor.

Under normal circumstances, you will not need to specify segment names.

See Chapter

"Memory

management, " in the Pro-

grammer's Guide for more on for objects.

Segment-naming control options allow you to rename segments and to reassign their groups and classes.

-zAname

This option changes the name of the code segment class to

name.

By default, the code segment is assigned to class CODE.

-zBname

This option changes the name of the uninitialized data segment class to

name.

By default, the uninitialized data segments are assigned to class

BSS.

-zCname

This option changes the name of the code segment to

name.

By default, the code segment is named

_TEXT, except for the medium, large and huge models, where the name is

filename_TEXT. (filename

here is the source file name.)

-zDname

This option changes the name of the uninitialized data segment to

name.

By default, the uninitialized data segment is named _BSS, except in the huge model, where no uninitialized data segment is generated.

-zEname

This option changes the name of the segment where far objects are put to

name.

By default, the segment name is the name of the far object followed by

_FAR. A name beginning with an asterisk (*) indicates that the default string should be used.

-zFname

This option changes the name of the class for far objects to

name.

By default, the name is FAR_DATA.

A name beginning with an asterisk (*) indicates that the default string should be used.

-zGname

This option changes the name of the uninitialized data segment group to

name.

By default, the data group is named DGROUP, except in the huge model, where there is no data group.

-zHname

This option causes far objects to be put into group

name.

By default, far objects are not put into a group.

A name beginning with an asterisk

(*) indicates that the default string should be used.

Chapter

The command-line compiler

177

-zPname

-zRname

-zSname

-zTname

-zX*

This option causes any output files to be generated with a code group for the code segment named

name.

This option sets the name of the initialized data segment to

name.

By default, the initialized data segment is named _DATA, except in the huge model, where the segment is named

filename_DATA.

This option changes the name of the initialized data segment group to

name.

By default, the data group is named DGROUP, except in the huge model, where there is no data group.

This option sets the name of the initialized data segment class to

name.

By default the initialized data segment class is named DATA.

This option uses the default name for X. For example, -zA

* assigns the default class name CODE to the code segment.

Compilation control options

See Appendix A for more on

precompiled headers.

Compilation control options allow you to control compilation of source files, such as whether your code is compiled as C or C++, whether to use precompiled headers, and what kind of Windows executable file is created. For more detailed information on how to create an Windows application, see Chapter 3.

-8

This option compiles and calls the assembler to process inline assembly code.

-c

-Efilename

This option compiles and assembles the named

.C, .CPP, and .ASM files, but does not execute a link command.

This option uses

name

as the name of the assembler to use. By default, TASM is used.

-H

This option causes the compiler to generate and use precompiled headers.

-H-

This option turns off generation and use of precompiled headers (this is the default).

-Hu

This option tells the compiler to use but not generate precompiled headers.

178

Borland

C++

User's Guide

-H=filename

Note that this option behaves differently from the

-p

option in Turbo C++ l.x.

-Pext

If you want to use your code written under Turbo Cor

Turbo C++ without having to

think about file-name extensions, use either -P- or

-P-C.

-p-

-P-ext

-s

-Tstring

-T-

This option sets the name of the file for precompiled headers. The default is TCDEF.SYM

(located in the BCC or BCCX startup directory).

This option also turns on generation and use of precompiled headers; that is, it also has the effect of-H.

This option compiles the named file to the specified

filename.obj.

This option causes the compiler to compile your code as c++ always, regardless of extension. The compiler will assume that all files have .CPP extensions unless a different extension is specified with the code.

This option causes the compiler to compile all files as C++; it changes the default extension to whatever you specify with

ext.

This option is available because some programmers use.C or another extension as their default extension for c++ code.

This option tells the compiler to compile a file as either C or C++, based on its extension. The default extension is .CPP. This option is the default.

This option also tells the compiler to compile code based on the extension (.CPP as C++ code, all other file-name extensions as C code).

It further specifies what the default extension is to be.

This option compiles the named source files and produces assembly language output files (.ASM), but does not assemble. When you use this option,

Borland C++ will include the C or C++ source lines as comments in the produced .ASM file.

This option passes

string

as an option to T ASM

(or as an option to the assembler defined with

-E).

This option removes all previously defined assembler options.

Chapter

The command-line compiler

179

These five options (-W, -WD,

-WDE, -WE, and -WS) relate to creating Windows applications. Note that you cannot use any of these options if you are using the

-Yoption (and vice versa).

-W

-WO

-WOE

-WE

Don't use this option for modules that will

compiled under the huge memory model.

-WS

This option creates the most general kind of Windows executable, although not necessarily the most efficient. The compiler generates export information for every far function. This does not mean that all far functions actually will be exported, it only means that export information is created for each far function. In order to actually export one of these functions, you must either use the _export keyword or add an entry for the function name in the EXPORTS section of the module definition file.

This option creates a module for use in a .DLL with all functions exportable.

This option creates a module for use in a .DLL with only explicit functions exportable.

This option creates an object module with only function explicitly designated with _export as exportable.

This option creates an .OB] with functions using smart callbacks. This option is recommended if you are writing Windows applications

(not

DLLs) which can assume SS

DS (most can). This option simplifies Windows programming; for instance, using it, you no longer need

MakeProclnstance or FreeProclnstance, nor do you need to export your WndProcs; instead, you can directly call a WndProc. Enabling this option results in faster Windows executables.

EMS and extended memory options

If you have extended or expanded memory and you are not running the command-line compiler in protected mode, you may still want to have the compiler use all available memory. That's where these options come in.

-Qe

This option instructs the compiler to use all EMS memory it can find. This is on by default for the real-mode version of the command-line compiler

(BCC).

It speeds up your compilations, especially for large source files.

180

Bor/and

c++

User's Guide

If you are in doubt about your systems' overall use of extended memory, don't use this option. Also, don't use this option when running

BCCX.EXE.

-Qe=yyyy

-Qe-

-Qx

This option instructs the compiler to use

yyyy

pages (in 16K page sizes) of EMS memory for itself.

This option instructs the compiler not to use any

EMS memory.

This option instructs BCC to use all extended memory it can find. Like -Qe, this speeds up compilations of large source files. However, unlike -Qe, this option has to be used with care, because another program might be already using extended memory and not be recognized.

-Qx=nnnn

For example, using the VDISK RAM disk driver with this option is safe, while some disk caches are not.

This option instructs the compiler to reserve

nnnn

Kbytes of extended memory for other programs and use the rest for itself. To figure out how much memory to reserve, you have to add up the memory that is used at the bottom of extended memory by resident programs like RAM disks or disk caches.

For example, if you use a disk cache, you might set it up so that it uses the first 512 Kbytes of extended memory. To tell the compiler to use the rest, you would specify

-Qx=512.

If you aren't sure how much extended memory is used by resident utilities like RAM disks or disk caches, it is better not to use this option.

-Qx=nnnn,yyyy

This option instructs the compiler to reserve

nnnn

Kbytes extended memory for other programs and

yyyy

Kbytes of extended memory for itself.

-Qx=,yyyy

This option instructs the compiler to reserve

yyyy

Kbytes of extended memory for itself. The comma is essential.

-Qx-

This option instructs the compiler not to use any extended memory. This is the default.

Chapter

The command-line compiler

181

c++

virtual tables

The -v option controls the c++ virtual tables. There are five variations of the

-v

option:

-v

-Vs

-YO

-V1

-Vf

Smart c++ virtual tables

Local C++ virtual tables

External C++ virtual tables

Public C++ virtual tables

Far C++ virtual tables

-v

-Vs

Use this option when you want to generate C++ virtual tables (and inline functions not expanded inline) so that only one instance of a given virtual table or inline function will be included in the program. This produces the smallest and most efficient executables, but uses .OBJ and .ASM extensions only available with

TLINK 3.0 and TASM 2.0 (or newer).

Use this option when you want Borland C++ to generate local virtual tables (and inline functions not expanded inline) such that each module gets its own private copy of each virtual table (or inline function) it uses. This option uses only standard .OBJ (and .ASM) constructs, but produces larger executables.

-YO, -V1 These options work together to create global virtual tables.

If you don't want to use the Smart or Local options (-V or -Vs), you can use -YO and -V1 to produce and reference global virtual tables. -YO generates external references to virtual tables; -V1 produces public definitions for virtual tables.

-Vf

When using these two options, at least one of the modules in the program must be compiled with the

-V1 option to supply the definitions for the virtual tables. All other modules should be compiled with the

-YO option to refer to that Public copy of the virtual tables.

You can use this option independently of or in conjunction with any of the other virtual table options.

It causes virtual tables to be created in the code segment instead of the data segment, and makes virtual table pointers into full 32-bit pointers (the latter

182

Borland

C++

User's Guide

is done automatically if you are using the huge memory model).

There are two primary reasons for using this option: to remove the virtual tables from the data segment, which may be getting full, and to be able to share objects (of classes with virtual functions) between modules that use different data segments (for example, a DLL and an executable using that DLL). You must compile all modules that may share objects either entirely with or entirely without this option. You can achieve the same effect by using the

huge

or

_export

modifiers on a class-by-class basis.

Linker options

See the section on TUNK in

Chapter

for

list of linker options.

-efilename

-Ix

-M

This option derives the executable program's name from

filename

by adding the file extension .EXE (the program name will then be

filename.EXE). filename

must immediately follow the

-e, with no intervening whitespace. Without this option, the linker derives the .EXE file's name from the name of the first source or object file in the file name list. The default extension is .DLL when you are suing -WO

or-WOE.

This option (which is a lowercase 1) passes option

x

to the linker. The option

-I-x

suppresses option

More than one option can appear after the

-I.

This option forces the linker to produce a full link map. The default is to produce no link map.

Environment options

When working with environment options, bear in mind that

Borland C++ recognizes two types of library files:

implicit

and

user-specified

(also known as

explicit

library files). These are defined and discussed on page 185.

-Ipath

This option (which is an uppercase I) causes the compiler to search

path

(the drive specifier or path name of a subdirectory) for include files (in

Chapter

The command-line compiler

183

184

-Lpath

-npath

addition to searching the standard places). A drive specifier is a single letter, either uppercase or lowercase, followed by a colon (:). A directory is any valid directory or directory path. You can use more than one -I directory option.

This option forces the linker to get the COx.OB} start-up object file and the Borland C++ library files (Cx.LIB, CPx.LIB, MATHx.LIB, EMU.LIB, and FP87.LIB) from the named directory. By default, the linker looks for them in the current directory.

This option places any .OBJ or .ASM files created by the compiler in the directory or drive named by

path.

Searching for include and library files

Borland C++ can search multiple directories for include and library files. This means that the syntax for the library directories

(-L) and include directories (-I) command-line options, like that of the #define option (-0), allows multiple listings of a given option.

Here is the syntax for these options:

Library directories:

Include directories:

-Ldirname[;dirname; ... ]

-Idirname[;dirname; ... ]

The parameter

dirname

used with -L and -I can be any directory or directory path.

You can enter these multiple directories on the command line in the following ways:

• You can "gang" multiple entries with a single -L or -I option, separating ganged entries with a semicolon, like this:

Bee

-Ldirnamel;dirname2;dirname3 -linel;inc2;ine3 myfile.e .

• You can place more than one of each option on the command line, like this:

Bee

-Ldirnamel -Ldirname2 -Ldirname3 -linel -line2 -line3 myfile.e

• You can mix ganged and multiple listings, like this:

Bee

-Ldirnamel;dirname2 -Ldirname3 -linel;ine2 -line3 myfile.e

Borland

C++

User's Guide

Note

If you list multiple

-L or -I

options on the command line, the result is cumulative: The compiler searches all the directories listed, or defines the specified constants, in order from left to right.

The IDE also supports multiple library directories through the

"ganged entry" syntax.

File-search algorithms

The Borland c++ include-file search algorithms search for the

#include

files listed in your source code in the following way:

Your code written under any version of Turbo

C or Turbo

C++ will work without problems in Borland C++.

• If you put an

#include <sornefile. h> statement in your source code, Borland c++ searches for somefile.h only in the specified include directories.

• If, on the other hand, you put an

#include "sornefile.h" statement in your code, Borland C++ searches for somefile.hfirst in the current directory; if it does not find the header file there, it then searches in the include directories specified in the command line.

The library file search algorithms are similar to those for include files:

• Implicit libraries:

Borland C++ searches for implicit libraries only in the specified library directories; this is similar to the search algorithm for

#include

<somefile.h>.

[Implicit library files are the ones Borland C++ automatically links in. These are the

Cx.LIB

and CWINx.LIB files, EMU. LIB or FP87.LIB,

MATHx.LIB, IMPORT. LIB, OVERLAY.LIB, and the start-up object files

(COx.OBJ, COWx.OBJ,

CODx.OBJ).]

• Explicit libraries:

Where Borland C++ searches for explicit

(user-specified) libraries depends in part on how you list the library file name. (Explicit library files are the ones you list on the command line or in a project file; these are file names with a

.LIB extension.)

• If you list an explicit library file name with no drive or directory (like this: rnylib.lib),

Borland C++ searches for that library in the current directory first. Then (if the first search was unsuccessful), it looks in the specified library directories.

This is similar to the search algorithm for

#include

"somefile

.h" .

Chapter

The command-line compiler

185

186

• If you list a user-specified library with drive and/or directory information (like this: c:mystuff\mylibl.lib),

Borland C++ searches

only

in the location you explicitly listed as part of the library path name and not in the specified library directories.

An annotated example

Here is an example of a real-mode Borland C++ command line that incorporates multiple library and include directory options.

Your current drive is C:, and your current directory is

C: \ TURBOC, where BCC.EXE resides. Your A drive's current position is A: \ ASTROLIB.

2. Your include files (.h or "header" files) are located in

C: \ TURBOC \ INCLUDE.

3. Your startup files (COT.

OBI,

COS.

OBI, ... ,

COH.OBJ) are in

C:\TURBOC.

4. Your standard Borland C++ library files (CS.LIB, CM.LIB, ... ,

MATHS.LIB, MATHM.Lffi, ... , EMU.LIB, FP87.LIB, and so forth) are in C: \ TURBOC\LIB.

5. Your custom library files for star systems (which you created and manage with TLIB) are in C: \ TURBOC\ST ARLIB. One of these libraries is P ARX. LIB.

6. Your third-party-generated library files for quasars are in the

A drive in \ASTROLIB. One of these libraries is WARP.LIB.

Under this configuration, you enter the following command:

BCC -rnm -Llib;starlib -linclude orion.c umaj.c parx.lib a:\astrolib\warp.lib

Borland C++ compiles ORION.C and

UMAI.C

.OBI

files.

It then searches C: \ TURBOC\INCLUDE for the include files in your source code, then links them with the medium model startup code (COM.OBJ), the medium model libraries (CM.LIB,

MA THM.LIB), the standard floating-point emulation library

(EMU.LIB), and the user-specified libraries (PARX.LIB and

WARP. LIB), producing an executable file named ORION.EXE.

It searches for the startup code in C:\ TURBOC (then stops because they're there); it searches for the standard libraries in

C: \ TURBOC\LIB (and stops because they're there).

When it searches for the user-specified library P ARX.LIB, the compiler first looks in the current directory, C: \ TURBOC. Not finding the library there, the compiler then searches the library

Borland C++ User's Guide

directories in order: first C: \ TURBOC\ LIB, then C: \ TURBOC\

STARLIB (where it locates P ARX.LIB).

Since an explicit path is given for the library WARP.LIB (A: \

ASTROLIB\WARP.LIB), the compiler only looks there.

Chapter

The command-line compiler

187

188

Bor/and c++

User's Guide

Chapter

Utilities

A p

T E

Utilities

Borland c++ comes with a host of powerful standalone utilities that you can use with your Borland C++ files or other modules.

These are

BGIOBJ, a conversion utility for graphics drivers and fonts

(documented online)

• CPP, the preprocessor (documented online)

GREP, a file-search utility (documented online)

• IMPDEF, which creates a module definition file

• IMPLIB, which generates an import library

.. MAKE, the standalone program manager

OBJXREF, an object module cross-referencer (documented online)

• PRJCFG, which updates options in a project file from a configuration file, or converts a project file to a configuration file (documented online)

• PRJCNVT, which converts Turbo C project files to the Borland

C++ format (documented online)

• PRJ2MAK, which converts Borland C++ project files to MAKE files (documented online)

THELP, the Turbo Help utility (documented online)

• TLIB, the Turbo Librarian

• TLINK, the Turbo Linker

• TOUCH, the file date and time changer (documented online)

189

• TRANCOPY, which copies transfer items from one project to another (documented online)

• TRIGRAPH, a character-conversion utility (documented online)

This chapter explains what IMPDEF, IMPLIB, MAKE, TLm, and

TLINK do, and illustrates, with code and command-line examples, how to use them. The rest of these utilities are documented in a text file called UTIL.DOC included with your distribution disks.

IMPDEF (module definition files)

An import library is used to provide access to a DLL S functions. See page

192

for more details.

IMPDEF works with IMPLIB to let you customize an import library to suit the needs of a specific application.

The syntax is

IMPDEF

DestName.DEF SourceName.DLL

This creates a module definition file named

DestName.DEF

from the file

SourceName.DLL.

The module definition file would look something like this:

LIBRARY

FileName

DESCRIPTION'Description'

EXPORTS

ExportFuncName @Ordinal

where

FileName

is the DLL's root filename,

Description

is the value of the DESCRIPTION statement if the DLL was previously linked with a module definition file that included a DESCRIPTION statement,

ExportFuncName

names an exported function and

Ordinal

is that function's ordinal value (an integer).

IMPDEF creates an editable source file that lists all of the export functions in the DLL. You can edit this .DEF file to contain only those functions that you would want to make available to a particular application, then run IMPLIB on the edited .DEF file.

This process results in an import library that contains import information for a specific subset of a DLL/s export functions.

For instance, let's say you're distributing a DLL that provides functions to be used by several applications. Every export

190

Borland

C++

User's Guide

Chapter

Utilities

IMPDEF

function in the DLL is defined with _export. Now, if all of the applications used all of the DLL's exports, then you could simply use IMPLIB to make one import library for the DLL, and deliver that import library with the DLL. This import library would provide import information for all of the DLL's exports. The import library could be linked to any application, thus eliminating the need for the particular application to list every

DLL function it uses in the IMPORTS section of its module definition file.

Now, let's say you want to give only a handful of the DLL's exports to a particular application. Ideally, you want a customized import library to be linked to that application-an import library that only provides import information for the subset of functions that the application will use. All of the other export functions in the DLL will be hidden to that client application.

To create an import library that satisfies these conditions, run

IMPDEF on the compiled and linked DLL. IMPDEF produces a module definition file that contains an EXPORT section listing all of the DLL's export functions. You can edit that module definition file, removing EXPORTS section entries for those functions that you don't want in the customized import library. Once you've removed the exports that you don't want, run IMPLIB on the module definition file. The result will be an import library that contains import information for only those export functions listed in the EXPORTS section of the module definition file.

This utility is particularly handy for a DLL that uses c++ classes, for two reasons. First, if you use the

_export

keyword when defining a class, all of the non-inline member functions and static data members for that class are exported. It's easier to let IMPDEF make a module definition file for you because it lists all the exported functions, automatically including the member functions and static data members.

Since the names of these functions are mangled, it would be very tedious to list them all in the EXPORTS section of a module definition file simply so that you could create an import library from the module definition file.

If you use IMPDEF to create the module definition file, it will include the ordinal value for each exported function, as well as that function's original name in a comment following the function entry, if the exported name is mangled. So, for instance, the module definition file created by

IMPDEF for a DLL that used

C++ classes would look something like this:

191

IMPDEF

LIBRARY

FileName

DESCRIPTION

'Description'

EXPORTS

MangledExportFuncName @Ordinal; ExportFuncName

where

FileName

is the DLL's root filename,

Description

is the value of the DESCRIPTION statement if the DLL was previously linked with a module definition file that included a DESCRIPTION statement,

MangledExportFuncName

provides the mangled name,

Ordinal

is that function's ordinal value (an integer), and

ExportFuncName

gives the function's original name.

IMPLIB (import libraries)

The IMPLIB utility creates an import library that can be substituted for part or all of the IMPORTS section of a module definition file for a Windows application.

If a module uses functions from DLLs, you have two ways to tell the linker about them:

• You can add an IMPORTS section to the module definition file and list every function from DLLs that the module will use .

• Or you can include the import library for the DLLs when you link the module.

If you've created a Windows application, you've already used at least one import library, IMPORT. LIB. IMPORT. LIB is the import library for the Windows USER.EXE, GDI.EXE, and KERNEL.EXE

DLLs. (IMPORT. LIB is linked automatically when you build a

Windows application in the IDE; if you've used only the IDE to build applications, then you might not have seen it before.)

An import library lists some or all of the exported functions for one or more DLLs. IMPLIB creates an import library directly from

DLLs or from module definition files for DLLs (or a combination of the two).

To create an import library for a DLL, type

IMPLIB

Options LibName DefFiles Dlls

192

Borland

C++

User's Guide

IMPLIB where

Options

is an optional list of one or more IMPLIB options,

LibName

(required) is the name for the new import library,

DefFiles

is a list of one or more existing module definition files for one or more DLLs, and

Dlls

is a list of one or more existing DLLs. You must specify at least one DLL or module definition file.

Table 7.1

IMPLIB options

You can use either a hyphen or a slash to precede IMPUB

options.

Option What it does

Ii

Tells IMPLIB to ignore WEP, the Windows exit procedure required to end a

DLL.

Use this option if you are specifying more than one DLL on the IMPUB command line.

Warning control:

Terse warnings.

Iv

Iw

Verbose warnings.

No warnings.

See page 190 for information on using IMPDEF and IMPLIB to customize an import library to suit the needs of a specific applicaiton.

Re-creating

IMPORT.L1B

When Microsoft releases new versions of Windows you will probably need to replace the current version of IMPORT. LIB with a new one. The easiest way to do this is to build it yourself.

This command line builds the current version of IMPORT. LIB:

IMPLIB /1 IMPORT.LIB GDI.EXE KERNEL.EXE USER.EXE KEYBOARD.DRV

SOUND.DRV WIN87EM.DLL

If Windows is extended so that it uses additional DLLs, any new

DLLs will also have to appear on the command line.

MAKE: The program manager

Borland's command-line MAKE, derived from the UNIX program of the same name, helps you keep the executable versions of your programs current. Many programs consist of many source files, each of which may need to pass through preprocessors, assemblers, compilers, and other utilities before being combined with the rest of the program. Forgetting to recompile a module that has been changed-or that depends on something you've changed-

Chapter

Utilities

193

To find out how to create a makefile for Windows programs, see Chapter 3, page 109.

can lead to frustrating bugs. On the other hand, recompiling

everything

just to be safe can be a tremendous waste of time.

MAKE solves this problem. You provide MAKE with a description of how the source and object files of your program are processed to produce the finished product. MAKE looks at that description and at the date stamps on your files, then does what's necessary to create an up-to-date version. During this process,

MAKE may invoke many different compilers, assemblers,linkers, and utilities, but it never does more than is necessary to update the finished program.

MAKE's usefulness extends beyond programming applications.

You can use MAKE to control any process that involves selecting files by name and processing them to produce a finished product.

Some common uses include text processing, automatic backups, sorting files by extension into other directories, and cleaning temporary files out of your directory.

How MAKE works

Cautionl

MAKE keeps your program up-to-date by performing the following tasks:

• Reads a special file (called a makefile) that you have created.

This file tells MAKE which

.OBI

and library files have to be linked in order to create your executable file, and which source and header files have to be compiled to create each

.OBI

file.

• Checks the time and date of each

.OBI

file against the time and date of the source and header files it depends on. If any of these is later than the

.OBI

file, MAKE knows that the file has been modified and that the source file must be recompiled.

• Calls the compiler to recompile the source file.

• Once all the

.OBI

file dependencies have been checked, checks the date and time of each of the

.OBI

files against the date and time of your executable file.

• If any of the

.OBI

files is later than the .EXE file, calls the linker to recreate the .EXE file.

MAKE relies completely upon the time stamp DOS places on each file. This means that, in order for MAKE to do its job, your system's time and date must be set correctly. If you own an AT or a PS/2, make sure that the battery is in good repair. Weak batteries can cause your system's clock to lose track of the date and time, and MAKE will no longer work as it should.

194 Borland

C++

User's Guide

MAKE

The original IBM PC and most compatibles didn't come with a built-in clock or calendar.

If your system falls into this category, and you haven't added a clock, be sure to set the system time and date correctly (using the DOS DATE and TIME commands) each time you start your machine.

Starting MAKE

MAKE stops if any command it has executed is aborted via a Control-Break. Thus, a

Control-Break stops the currently executing command and MAKE as well.

To use MAKE, type make at the DOS prompt. MAKE then looks for a file specifically named MAKEFILE.

MAKE can't find

MAKE FILE, it looks for MAKEFILE.MAK; if it can't find that or

BUILTINS.MAK (described later), it halts with an error message.

What if you want to use a file with a name other than MAKEFILE or MAKEFILE.MAK? You give MAKE the file (-f) option, like this:

MAKE -fMYFILE.MAK

The general syntax for MAKE is make

[option [option]] [target [target ... ]]

where

option

is a MAKE option (discussed later), and

target

is the name of a target file to make.

Here are the MAKE syntax rules:

• The word

make

is followed by a space, then a list of make options.

• Each make option must be separated from its adjacent options by a space. Options can be placed in any order, and any number of these options can be entered (as long as there is room in the command line). All options that do not specify a string (-s or -a, for example) can have an optional- or + after them. This specifies whether you wish to turn the option off (-) or on

(+).

The list of MAKE options is followed by a space, then an optional list of targets.

Each target must also be separated from its adjacent targets by a space. MAKE evaluates the target files in the order listed, recompiling their constituents as necessary.

If the command line does not include any target names, MAKE uses the first target file mentioned in an explicit rule. If one or more targets are mentioned on the command line, they will be built as necessary.

Chapter

Utilities

195

MAKE

The BUILTINS.MAK file You will often find that there are MAKE macros and rules that you use again and again. There are three ways of handling them.

• First, you can put them in every makefile you create.

• Second, you can put them all in one file and use the

!include

directive in each makefile you create. (See page 215 for more on directives. )

• Third, you can put them all in a BUlL TINS.MAI< fil~.

Each time you run MAKE, it looks for a BUlL TINS.MAK file; however, there is no requirement that any BUlL TINS.MAK file exist. If MAKE finds a BUlL TINS.MAK file, it interprets that file first. If MAKE cannot find a BUlL TINS.MAK file, it proceeds directly to interpreting MAl<EFILE (or whatever makefile you specify).

The first place MAKE searches for BUlL TINS.MAI< is the current directory.

If it's not there,

and

if you're running under DOS 3.0 or higher, MAKE then searches the directory from which

MAKE.EXE was invoked. You should place the BUlL TINS.MAK file in the same directory as the MAKE.EXE file.

MAKE always searches for the makefile in the current directory only. This file contains the rules for the particular executable program file being built. Both BUlL TINS.MAK and the makefile files have identical syntax rules.

MAKE also searches for any

!include

files (see page 217 for more on this MAKE directive) in the current directory. If you use

the-I

(include) option, it will also search in the directory specified with the

-I

option.

Command-line options

Here's a complete list of MAl<E's command-line options. Note that case (upper or lower)

is

significant; the option -d is not a valid substitution for

-D.

196 Borland C++ User's Guide

MAKE

Table 7.2: MAKE options

Option

-1 or -h

-a

-8

-Didentifier

-Diden=string

-ffilename

-i

-I

directory

-K

-n

-s

-5

-Uidentifier

-W

What it does

Prints a help message. The default options are displayed with plus signs following.

Causes an automatic dependency check on

.OBI

files.

Builds all targets regardless of file dates.

Defines the named identifier to the string consisting of the single character 1 (one).

Defines the named identifier

iden

to the string after the equal sign. The string cannot contain any spaces or tabs.

Uses

filename

as the MAKE file.

Hfilename

does not exist and no extension is given, tries

FILENAME.MAK.

Does not check (ignores) the exit status of all programs run. Continues regardless of exit status. This is equivalent to putting '-' in front of all commands in the MAKEFILE

(described below).

Searches for include files in the indicated directory (as well as in the current directory).

Keeps (does not erase) temporary files created by MAKE. All temporary files have the form

MAKEnnnn.$$$,

where

nnnn

ranges from 0000 to 9999. See page 202 for more on temporary files.

Prints the commands but does not actually perform them. This is useful for debugging a makefile.

Does not print commands before executing. Normally, MAKE prints each command as it is about to be executed.

Swaps MAKE out of memory while executing commands. This significantly reduces the memory overhead of MAKE, allowing it to compile very large modules.

Undefines any previous definitions of the named identifier.

Writes the current specified non-string options (like -s and

-a) to MAKE.EXE. (This makes them default.)

A simple use of

MAKE

MAKE can a/so backup files, pull files out of different subdirectories, and even automatically run your programs should the data files they use be modified.

For our first example, let's look at a simple use of

MAKE that doesn't involve programming. Suppose you're writing a book, and decide to keep each chapter of the manuscript in a separate file. (Let's assume, for the purposes of this example, that your book is quite short: It has three chapters, in the files CHAP1.MSS,

CHAP2.MSS, and CHAP3.MSS.) To produce a current draft of the book, you run each chapter through a formatting program, called

FORM.EXE, then use the DOS COPY command to concatenate the outputs to make a single file containing the draft, like this:

Chapter

Utilities

197

MAKE

198

Chap1.MSS

Chap2.MSS

Chap3.MSS

/onn.9>

Chapt1.TXT

/onn.9>

Chapt2.TXT

/orm.9>

Chap3.TXT

Book.TXT

Like programming, writing a book requires a lot of concentration.

As you write, you may modify one or more of the manuscript files, but you don't want to break your concentration by noting which ones you've changed. On the other hand, you don't want to forget to pass any of the files you've changed through the formatter before combining it with the others, or you won't have a fully updated draft of your book!

One inelegant and time-consuming way to solve this problem is to create a batch file that reformats every one of the manuscript files. It might contain the following commands:

FORM CHAP1.MSS

FORM CHAP2.MSS

FORM CHAP 3 .MSS

COPY fA CHAP1.TXT+CHAP2.TXT+CHAP3.TXT BOOK. TXT

Running this batch file would always produce an updated version of your book. However, suppose that, over time, your book got bigger and one day contained 15 chapters. The process of reformatting the entire book might become intolerably long.

MAKE can come to the rescue in this sort of situation. All you need to do is create a file, usually named MAKEFILE, which tells

MAKE what files BOOK.TXT depends on and how to process them. This file will contain rules that explain how to rebuild

BOOK. TXT when some of the files it depends on have been changed.

In this example, the first rule in your makefile might be

BOOK. TXT: CHAP1.TXT CHAP2.TXT CHAP3.TXT

COPY fA CHAP1.TXT+CHAP2.TXT+CHAP3.TXT BOOK. TXT

What does this mean? The first line (the one that begins with book. txt:) says that BOOK. TXT depends on the formatted text of

Borland

C++

User's Guide

Chapter

Utilities

MAKE

each of the three chapters. If any of the files that BOOK.TXT depends on are newer than BOOK. TXT itself, MAKE must rebuild

BOOK.TXT by executing the COpy command on the subsequent line.

This one rule doesn't tell the whole story, though. Each of the chapter files depends on a manuscript (.MSS) file. If any of the

CHAP?TXT files is newer than the corresponding .MSS file, the

.MSS file must be recreated. Thus, you need to add more rules to the makefile as follows:

CHAP1.TXT: CHAP1.MSS

FORM CHAPl.MSS

CHAP2.TXT: CHAP2.MSS

FORM CHAP2.MSS

CHAP3.TXT: CHAP3.MSS

FORM CHAP3.MSS

Each of these rules shows how to format one of the chapters, if necessary, from the original manuscript file.

MAKE understands that it must update the files that another file depends ,on before it attempts to update that file. Thus, if you change CHAP3.MSS, MAKE is smart enough to reformat Chapter

3 before combining the .TXT files to create BOOK.TXT.

We can add one more refinement to this simple example. The three rules look very much the same-in fact, they're identical except for the last character of each file name. And, it's pretty easy to forget to add a new rule each time you start a new chapter. To solve these problems, MAKE allows you to create something called an

implicit rule,

which shows how to make one type of file from another, based on the files' extensions. In this case, you can replace the three rules for the chapters with one implicit rule:

.MSS.TXT:

FORM

.MSS

This rule says, in effect, "If you need to make a .TXT file out of an

.MSS file to make things current, here's how to do it." (You'll still have to update the first rule-the one that makes BOOK.TXT, so that MAKE knows to concatenate the new chapters into the output file. This rule, and others following, make use of a

macro.

See page 211 for an in-depth discussion of macros.)

199

MAKE

Once you have the makefile in place, all you need to do to create an up-to-date draft of the book is type a single command at the

DOS prompt: MAKE.

Creating makefiles

Creating a program from an assortment of program files, include files, header files, object files, and so on, is very similar to the text-processing example you just looked at. The main difference is that the commands you'll use at each step of the process will invoke preprocessors, compilers, assemblers, and linkers instead of a text formatter and the DOS COPY command. Let's explore how to create makefiles-the files that tell MAKE how to do these things-in greater depth.

A makefile contains the definitions and relationships needed to help MAKE keep your program(s) up-to-date. You can create as many makefiles as you want and name them whatever you want;

MAKEFILE is just the default name that MAKE looks for if you don't specify a makefile when you run MAKE.

You create a makefile with any ASCII text editor, such as the IDE built-in editor, Sprint, or SideKick. All ru1es, definitions, and directives end at the end of a line. If a line is too long, you can continue it to the next line by placing a backslash (\) as the last character on the line.

Use whitespace (blanks and tabs) to separate adjacent identifiers

(such as dependencies) and to indent commands within a rule.

Components of a makefile

Creating a makefile is basically like writing a program, with definitions, commands, and directives. These are the constructs allowed in a makefile:

• comments

• explicit ru1es

• implicit rules

• macro definitions

• directives:

• file inclusion directives

• conditional execution directives

200

Borland

C++ User's Guide

MAKE

• error detection directives

• macro undefinition directives

Let's look at each of these in more detail.

Comments Comments begin with a pound sign

(#) character; the rest of the line following the # is ignored by MAKE. Comments can be placed anywhere; they don't have to start in a particular column.

A backslash will

not

continue a comment onto the next line; instead, you must use a

# on each line. In fact, you cannot use a backslash as a continuation character in a line that has a comment.

If the backslash precedes the #, it is no longer the last character on the line; if it follows the #, then it is part of the comment itself.

Here are some examples of comments in a makefile:

Explicit and implicit rules are discussed following the section

commands.

Makefile for my book

# This file updates the file BOOK. TXT each time I

# change one of the .MSS files

Explicit rule to make BOOK. TXT from six chapters. Note the

# continuation lines.

BOOK. TXT: CHAP1.TXT CHAP2.TXT CHAP3.TXT\

CHAP4.TXT CHAPS. TXT CHAP6.TXT

COPY /A CHAP1.TXT+CHAP2.TXT+CHAP3.TXT+CHAP4.TXT+\

CHAPS.TXT+CHAP6.TXT BOOK. TXT

Implicit rule to format individual chapters

.MSS.TXT:

FORM $*.MSS

Command lists

Both explicit and implicit rules (discussed later) can have lists of commands. This section describes how these commands are processed by MAKE.

Commands in a command list take the form

[ prefix ... ] command_body

Each command line in a command list consists of an (optional) list of prefixes, followed by a single command body.

Chapter

Utilities

201

MAKE

Prefixes

The prefixes allowed in a command modify the treatment of these commands by MAKE. The prefix is either the at-sign

(@) or a hyphen (-) followed immediately by a number.

Table 7.3

MAKE prefixes

Prefix

Exit codes are those returned by the executed commands

(within the program).

-num

What it does

Prevents MAKE from displaying the command before executing it.

The display is hidden even if the

-s option is not given on the MAKE command line. This prefix applies only to the command on which it appears.

Affects how MAKE treats exit codes. If a number

(num)

is provided, then MAKE aborts processing only if the exit status exceeds the number given.

In this example, MAKE aborts only if the exit status exceeds 4:

-4 MYPROG SAMPLE.X

If no

-num

prefix is given and the status is nonzero, MAKE stops and deletes the current target file.

With a hyphen but no number, MAKE will not check the exit status at all. Regardless of the exit status, MAKE continues.

Command body

The command body is treated exactly as if it were entered as a line to the DOS command line, with the exception that pipes (I) are not supported.

In addition to the

<, >,

and»

redirection operators, MAKE adds

the« and &&

operators. These operators create a file on the fly for input to a command. The « operator creates a temporary file and redirects the command's standard input so that it comes from the created file. If you have a program that accepted input from

stdin,

the command

MYPROG «!

This is a test would create a temporary file containing the string "This is a test \ nil , redirecting it to be the sole input to

myprog.

The exclamation point (!) is a delimiter in this example; you can use any character except

# or \ as a delimiter for the file. The first line containing the delimiter character as its first character ends the file. The rest of the line following the delimiter character (in this

202

Borland

C++ User's Guide

MAKE

Macros are covered starting on page

277. case, an exclamation point) is considered part of the preceding command.

The

operator is similar to

«.

It creates a temporary file, but instead of making the file the standard input to the command, the

operator is replaced with the temporary file's name. This is useful when you want MAKE to create a file that's going to be used as input to a program. The following example creates a

"response file" for TLINK:

MYPROG.EXE:

(MYOBJS)

TLINK

@&&! cos

(MYOBJS)

(MYLIBS) EMU.LIB MATHS.LIB CS.LIB

Note that macros (indicated by $ signs) are expanded when the file is created. The

$* is replaced with the name of the file being built, without the extension, and $(MYOBJS) and $(MYLIBS) are replaced with the values of the macros MYOBJS and MYLIBS.

Thus, TLINK might see a file that looks like this: cos

A.OBJ B.OBJ C.OBJ D.OBJ

MYPROG

W.LIB X.LIB Y.LIB Z.LIB EMU.LIB MATHS.LIB CS.LIB

. . All temporary files are deleted unless you use the

-K

commandline option. Use the

-K

option to "debug" your temporary files if they don't appear to be working correctly.

Batching programs

MAKE allows utilities that can operate on a list of files to be batched. Suppose, for example, that MAKE needs to submit several C files to Borland c++ for processing. MAKE could run

BCC.EXE once for each file, but it's much more efficient to invoke

BCC.EXE with a list of all the files to be compiled on the command line. This saves the overhead of reloading Borland c++ each time.

MAKE's batching feature lets you accumulate the names of files to be processed by a command, combine them into a list, and invoke that command only once for the whole list.

Chapter

Utilities

203

MAKE

204

To cause MAKE to batch commands, you use braces in the command line:

command {batch-item} ... rest-oj-command

This command syntax delays the execution of the command until

MAKE determines what command (if any) it has to invoke next. If the next command is identical except for what's in the braces, the two commands will be combined by appending the parts of the commands that appeared inside the braces.

Here's an example that shows how batching works. Suppose

MAKE decides to invoke the following three commands in succession:

Bee

{filel.c }

Bee

{file2.c }

Bee

{file3.c }

Rather than invoking Borland c++ three times, MAKE issues the single command

Bee filel.c file2.c file3.c

Note that the spaces at the ends of the file names in braces are essential to keep them apart, since the contents of the braces in each command are concatenated exactly as-is.

Here's an example that uses an implicit rule. Suppose your makefile had an implicit rule to compile C programs to

.OBI

files:

.c.obj:

Bee

-c {$< }

As MAKE uses the implicit rule on each C file, it expands the macro

into the actual name of the file and adds that name to the list of files to compile. (Again, note the space inside the braces to keep the names separate.) The list grows until one of three things happens:

• MAKE discovers that it has to run a program other than BCC

• there are no more commands to process

• MAKE runs out of room on the command line

MAKE runs out of room on the command line, it puts as much as it can on one command line, then puts the rest on the next command line. When the list is done, MAKE invokes BCC (with the -c option) on the whole list of files at once.

Borland

C++

User's Guide

Chapter

Utilities

MAKE

Executing DOS commands

MAKE executes the DOS "internal" commands listed here by invoking a copy of COMMAND.COM to perform them: break cd chdir cls copy ctty date del dir echo erase for md mkdir path prompt rd rem ren rename rmdir set time type ver verify vol

MAKE searches for any other command name using the DOS search algorithm:

MAKE first searches for the file in the current directory, then searches each directory in the path.

2. In each directory, MAKE first searches for a file of the specified name with the extension .COM. If it doesn't find it, it searches for the same file name with an .EXE extension. Failing that,

MAKE searches for a file by the specified name with a .BAT extension.

MAKE finds a .BAT file, it invokes a copy of COM-

MAND.COM to execute the batch file.

If you supply a file-name extension in the command line, MAKE searches only for that extension. Here are some examples:

This command causes COMMAND.COM to change the current directory to C: \ include: cd c:\include

MAKE uses the full search algorithm in searching for the appropriate files to perform this command: tlink lib\cOs x y,z,z,lib\cs

• MAKE searches for this file using only the .COM extension: myprog.com geo.xyz

• MAKE executes this command using the explicit file name provided: c:\myprogs\fil.exe -r

205

MAKE

206

Explicit rules The first rule in the example on page 201 is an explicit rule-a rule that specifies complete file names explicitly. Explicit rules take the form

target [target] ... : [source source ... ]

[command]

where

target

is the file to be updated,

source

is a file on which

target

depends, and

command

is any valid DOS command

(including invocation of .BAT files and execution of .COM and

.EXE files).

Explicit rules define one or more target names, zero or more source files, and an optional list of commands to be performed.

Target and source file names listed in explicit rules can contain normal DOS drive and directory specifications; they can also contain wildcards.

. . Syntax here is important.

• target

must be at the start of a line (in column 1).

• The

source

file(s) must be preceded by at least one space or tab, after the colon.

• Each

command

must be indented, (must be preceded by at least one blank or tab). As mentioned before, the backslash can be used as a continuation character if the list of source files or a given command is too long for one line.

Both the source files and the commands are optional; it is possible to have an explicit rille consisting only of

target [target ... J

followed by a colon.

The idea behind an explicit rule is that the command or commands listed will create or update

target,

usually using the

source

files. When MAKE encounters an explicit rille, it first checks to see if any of the

source

files are themselves target files elsewhere in the makefile. If so, MAKE evaluates that rille first.

Once all the

source

files have been created or updated based on other rilles, MAKE checks to see if

target

exists. If not, each

command

is invoked in the order given. If

target

does exist, its time and date of last modification are compared against the time and date for each

source.

If any

source

has been modified more recently than

target,

the list of commands is executed.

Borland C++ User's Guide

Chapter

Utilities

MAKE

A given file name can occur on the left side of an explicit rule only once in a given execution of MAKE.

Each command line in an explicit rule begins with whitespace.

MAKE considers all lines following an explicit rille to be part of the command list for that rille, up to the next line that begins in column 1 (without any preceding whitespace) or to the end of the file. Blank lines are ignored.

Special considerations

An explicit rille with no command lines following it is treated a little differently than an explicit rille with command lines .

.. If an explicit rille includes commands, the only files that the target depends on are the ones listed in the explicit rille .

.. If an explicit rille has no commands, the targets depend on two sets of files: the files given in the explicit rule, and any file that matches an implicit rille for the target(s). This lets you specify a dependency to be handled by an implicit rule. For example,

.c.obj

Bee

-c $< prog .obj: prog.obj depends on prog.c; MAKE executes the command line

Bee

-c prog.c if

PROG.OBI

is out of date.

Examples

Here are some examples of explicit rilles:

1. prog.exe: myprog.obj prog2.obj

Bee

myprog.obj prog2.obj

2. myprog.obj: myprog.c include\stdio.h

Bee

-c myprog.c

3. prog2.obj: prog2.c include\stdio.h

Bee

-c -K prog2.c

The three examples are from the same makefile. Only the modilles affected by a change are rebuilt. If PROG2.C is changed, it's the only one recompiled; the same holds true for MYPROG.C. But if the include file stdio.h is changed, both are recompiled. (The link

207

MAKE

208

step is done if any of the

.OBI

files in the dependency list have changed, which will happen when a recompile results from a change to a source file.)

Automatic dependency checking

Borland C++ works with MAKE to provide automatic dependency checking for include files. BCC and BC produce

.OBI

files that tell MAKE what include files were used to create those

.OBI

files. MAKE's

-a

command-line option checks this information and makes sure that everything is up-to-date.

When MAKE does an automatic dependency check, it reads the include files' names, times, and dates from the

.OBI

file. The auto dependency check will also work for include files inside of include files. If any include files have been modified, MAKE causes the

.OBI

file to be recompiled. For example, consider the following explicit rule: myprog.obj: myprog.c include\stdio.h

BCC -c myprog.c

Now assume that the following source file, called MYPROG.C, has been compiled with BCC (version 2.0 or later):

#include <stdio.h>

#include "dcl.h" void myprog() {}

If you then invoke MAKE with the following command line make -a myprog.obj it checks the time and date of MYPROG.C, and also of stdio.h and dcl.h.

Implicit rules MAKE allows you to define

implicit

rules as well as explicit ones.

Implicit rules are generalizations of explicit rules; they apply to all files that have certain identifying extensions.

Here's an example that illustrates the relationship between the two rules. Consider this explicit rule from the preceding example.

The rule is typical because it follows a general principle:

.OBI

file is dependent on the .C file with the same file name and is created by executing BCC. In fact, you might have a makefile where you have several (or even several dozen) explicit rules following this same format.

Borland

C++

User's Guide

Chapter

Utilities

MAKE

By rewriting the explicit rule as an implicit rule, you can eliminate all the explicit rules of the same form. As an implicit rule, it would look like this:

.c.obj:

BCC

-c $<

This rule means

Any file with the extension .C can be translated to a file of the same name with the extension .OBJ using this sequence of commands." The .OBJ file is created with the second line of the rule, where

$< represents the file's name with the source

(.C) extension. (The symbol

$< is a special macro. Macros are discussed starting on page 211. The

$< macro will be replaced by the full name of the appropriate .C source file each time the command executes.)

Here's the syntax for an implicit rule:

.source _extension. target _extension:

[command]

As before, the commands are optional and must be indented.

source_extension

(which must begin with its period in column 1) is the extension of the source file; that is, it applies to any file having the format

fname.source_extension

Likewise, the

target_extension

refers to the file

fname.target _extension

where

fname

is the same for both files. In other words, this implicit rule replaces all explicit rules having the format

fname.targeCextension: fname.source_extension

[command]

Note

for any

fname.

MAKE uses implicit rules if it can't find any explicit rules for a given target, or if an explicit rule with no commands exists for the target.

The extension of the file name in question is used to determine which implicit rule to use. The implicit rule is applied if a file is

209

MAKE

210 found with the same name as the target, but with the mentioned source extension.

For example, suppose you had a makefile (named MAKEFILE) whose contents were

.c.obj:

Bee

-c $<

If you had a C program named RA TIO.C that you wanted to compile to RATIO.OBJ, you could use the command make ratio.obj

MAKE would take RATIO.OBJ to be the target. Since there is no explicit rule for creating RA TIO.OBJ, MAKE applies the implicit rule and generates the command

Bee

-c ratio.c which, of course, does the compile step necessary to create

RATIO.OBI·

MAKE also uses implicit rules if you give it an explicit rule with no commands. Suppose you had the following implicit rule at the start of your makefile:

.c.obj:

Bee

-c $<

You could then remove the command from the rule: myprog.obj: myprog.c include\stdio.h

Bee

-c myprog.c and it would execute exactly as before.

If you're using Borland c++ and you enable automatic dependency checking in MAKE, you can remove all explicit dependencies that have .OBJ files as targets. With automatic dependency checking enabled and implicit rules, the three-rule C example shown in the section on explicit rules becomes

.c.obj:

Bee

-c $< prog.exe: myprog.obj prog2.obj tlink lib\cOs myprog prog2, prog, , lib\cs

You can write several implicit rules with the same target extension.

If more than one implicit rule exists for a given target extension, the rules are checked in the order in which they appear in

Borland

C++

User's Guide

Chapter

Utilities

MAKE

the makefile, until a match is found for the source extension, or until MAKE has checked all applicable rwes.

MAKE uses the first implicit rwe that involves a file with the source extension. Even if the commands of that ru1e fail, no more implicit rwes are checked.

All lines following an implicit rule, up to the next line that begins without whitespace or to the end of the file, are considered to be part of the command list for the ru1e.

Macros

Often, you'll find yourself using certain commands, file names, or options again and again in your makefile. For instance, if you're writing a e program that uses the medium memory model, all your Bee commands will use the option

-mm,

which means to compile to the medium memory model. But suppose you wanted to switch to the large memory model. You could go through and change all the

-mm

options to

-ml.

Or, you could define a macro.

macro

is a name that represents some string of characters. A macro definition gives a macro name and the expansion text; thereafter, when MAKE encounters the macro name, it replaces the name with the expansion text.

Suppose you defined the following macro at the start of your makefile:

MODEL

= m

This line defines the macro

MODEL, which is now equivalent to the string m.

Using this macro, you cowd write each command to invoke the e compiler to look something like this:

Bee

-c -m$(MODEL) myprog.c

When you run MAKE, each macro (in this case,

(MODEL) ) is replaced with its expansion text (here, m). The command that's actually executed would be

Bee

-c -rom myprog.c

Now, changing memory models is easy. If you change the first line to

MODEL

1 you've changed all the commands to use the large memory model.

In fact, if you leave out the first line altogether, you can specify which memory model you want each time you run MAKE, using the -0 (define) command-line option:

211

MAKE

212 make -DMODEL

This tells MAKE to treat

MODEL

as a macro with the expansion text 1.

Defining macros

Macro definitions take the form

macro_name

expansion text

where

macro_name

is the name of the macro.

macro_name

should be a string of letters and digits with no whitespace in it, although you can have whitespace between

macro_name

and the equal sign

(=). The

expansion text

is any arbitrary string containing letters, digits, whitespace, and punctuation; it is ended by newline.

macro_name

has previously been defined, either by a macro definition in the makefile or by the

-D

option on the MAKE command line, the new definition replaces the old.

Case is significant in macros; that is, the macro names

model,

Model, and MODEL

are all different.

Using macros

You invoke macros in your makefile using this format

$(macro_name)

You need the parentheses for all invocations, even if the macro name is just one character long (with the exception of the predefined macros). This construct-$ (macro_name)-is known as a

macro invocation.

When MAKE encounters a macro invocation, it replaces the invocation with the macro's expansion text. If the macro is not defined, MAKE replaces it with the null string.

Special considerations

Macros in macros:

Macros cannot be invoked on the left side

(macro_name)

of a macro definition. They can be used on the right side

(expansion text),

but they are not expanded until the macro being defined is invoked. In other words, when a macro invocation is expanded, any macros embedded in its expansion text are also expanded.

Borland

C++

User's Guide

MAKE

See page

275

for information on directives.

Macros in rules:

Macro invocations are expanded immediately in rule lines.

Macros in directives: Macro invocations are expanded immediately in !if and !elif directives. If the macro being invoked in an

!if or

!elif directive is not currently defined, it is expanded to the value 0 (FALSE).

Macros in commands:

Macro invocations in commands are expanded when the command is executed.

Predefined macros

MAKE comes with several special macros built in:

$d, $*, $<, $:,

$., and $&. The first is a test to see if a macro name is defined; it's used in the conditional directives

!if and

!elif.

The others are file name macros, used in explicit and implicit rules. In addition, the current DOS environment strings (the strings you can view and set using the DOS SET command) are automatically loaded as macros. Finally, MAKE defines two macros: __ MSDOS_

- J

defined to be 1 (one); and __

- J

defined to be MAKE's version number in hexadecimal (for this version, Ox0300).

Table 7.4

MAKE macros

Macro

What it does

Defined test macro

Base file name macro with path

Full file name macro with path

Path only macro

Full file name macro, no path

Base file name macro, no path

Defined Test Macro ($d): The defined test macro ($d) expands to 1 if the given macro name is defined, or to 0 if it is not. The content of the macro's expansion text does not matter. This special macro is allowed only in

!if and

!elif directives.

For example, suppose you want to modify your makefile so that if you don't specify a memory model, it'll use the medium one. You could put this at the start of your makefile:

!if !$d(MODEL) # if MODEL is not defined

MODEL=m # define it to m (MEDIUM)

!endif

If you then invoke MAKE with the command line make -DMODEL=l

Chapter

Utilities

213

MAKE

214 then

MODEL

is defined as 1. If, however, you just invoke MAKE by itself, make then

MODEL

is defined as

m,

your

default" memory model.

File name macros

The various file name macros work in similar ways, expanding to some variation of the full path name of the file being built.

Base file name macro ($*): The base file name macro is allowed in the commands for an explicit or an implicit rule. This macro

($*) expands to the file name being built, excluding any extension, like this:

File name is A:\P\TESTFILE.C

$* expands to A:\P\TESTFILE

For example, you could modify this explicit rule prog.exe: myprog.obj prog2.obj tlink lib\cOs myprog prog2, prog, , lib\cs to look like this: prog.exe: myprog.obj prog2.obj tlink lib\cOs myprog prog2, $*, , lib\cs

When the command in this rule is executed, the macro

$* is replaced by the target file name without an extension and with a path. For implicit rilles, this macro is very useful.

For example, an implicit rille might look like this:

.c.obj:

BCC -c $*

Full file name macro ($<):

The full file name macro

($<) is also used in the commands for an explicit or implicit rule. In an explicit rille,

$< expands to the full target file name (including extension), like this:

File name is A:\P\TESTFILE.C

$< expands to A:\P\TESTFILE.C

For example, the rille mylib.obj: mylib.c copy $< \oldobjs

BCC -c $*

Borland C++ User's Guide

MAKE copies MYLIB.OBJ to the directory \OLDOBJS before compiling

MYLIB.C.

In an implicit rule, $< takes on the file name plus the source extension. For example, the implicit rule

.c.obj:

Bee -c $*.c produces exactly the same result as

.c.obj:

Bee -c

$< because the extension of the target file name

must

be .C.

File-name path macro ($:): This macro expands to the path name

(without the file name), like this:

File name is A:\P\TESTFILE.e

$: expands to A:\P\

File-name and extension macro ($.):

This macro expands to the file name, with an extension but without the path name, like this:

File name is A:\P\TESTFILE.e

$. expands to TESTFILE.e

File name only macro ($&): This macro expands to the file name only, without path or extension, like this:

File name is A:\P\TESTFILE.e

$& expands to TESTFILE

Directives

Borland's MAKE allows something that other versions of MAKE don't: directives similar to those allowed in C, assembler, and

Turbo Pascal. You can use these directives to perform a variety of useful and powerful actions. Some directives in a makefile begin with an exclamation point

(!) as the first character of the line.

Others begin with a period. Here is the complete list of MAKE directives:

Table 7.5

MAKE directives

. autodepend

!elif

!else

!endif

!error

Iif

.ignore

Turns on autodependency checking .

Conditional execution.

Causes MAKE to stop and print an error message.

Conditional execution.

Tells MAKE to ignore return value of a command .

Chapter

Utilities

215

MAKE

Table 7.5: MAKE directives (continued)

!include

. noautodepend

. noignore

.nosilent

. noswap

.path.ext

.silent

. swap lundef

Specifies a file to include in the makefile.

Turns off autodependency checking .

Turns off

.Ignore .

Tells MAKE to print commands before executing them.

Tells MAKE to not swap itself in and out of memory .

Gives MAKE a path to search for files with extension

.EXT.

Tells MAKE to not print commands before executing them.

Tells MAKE to swap itself in and out of memory .

Causes the definition for a specified macro to be forgotten.

Dot directives Each of the following directives has a corresponding commandline option, but takes precedence over that option. For example, if you invoke MAKE like this: make -a but the makefile has a

.noautodepend

directive, then autodependency checking will be off .

. autodepend and .noautodepend turn

on or off auto dependency checking. They correspond to the

-a

command-line option .

.ignore and .noignore

tell MAKE to ignore the return value of a command, much like placing the prefix - in front of it (described earlier). They correspond to the

-i

command-line option .

. silent and .nosilent

tell MAKE whether or not to print commands before executing them. They correspond to the

-s

command-line option .

. swap

and

.noswap

tell MAKE to swap itself out of memory. They correspond to the -5 option .

. path.ext

This directive, placed in a makefile, tells MAKE where to look for files of the given extension. For example, if the following is in a makefile:

.path.c

C:\CSOURCE

.c.obj:

BCC -c

216

Borland

C++

User's Guide

MAKE

trnp.exe: trnp.obj

BCC trnp.obj

MAKE will look for TMP.C, the implied source file for TMP.OBJ, in C: \ CSOURCE instead of the current directory.

The

.path

is also a macro that has the value of the path. The following is an example of the use of

.path.

The source files are contained in one directory, the .OBJ files in another, and all the

.EXE files in the current directory .

. path.c

.path.obj

C:\CSOURCE

C:\OBJS

.c.obj:

BCC -c -o$(.path.obj)\$& $<

. obj. exe:

BCC -e$&.exe $< trnp.exe: trnp.obj

File-inclusion directive

A file-inclusion directive

(!include)

specifies a file to be included into the makefile for interpretation at the point of the directive. It takes the following form:

!include

"filename"

You can nest these directives to any depth.

If an include directive attempts to include a file that has already been included in some outer level of nesting (so that a nesting loop is about to start), the inner include directive is rejected as an error.

How do you use this directive? Suppose you created the file

MODEL.MAC that contained the following:

! if ! $d (MODEL)

MODEL=rn

!endif

You could use this conditional macro definition in any makefile by including the directive

!include "MODEL.MAC"

When MAKE encounters

!include,

it opens the specified file and reads the contents as if they were in the makefile itself.

Chapter

Utilities

217

MAKE

Conditional execution directives

Conditional execution directives (!if,

!elif, !else,

and

!endif)

give you a measure of flexibility in constructing makefiles. Rules and macros can be made conditional, so that a command-line macro definition (using the

-D

option) can enable or disable sections of the makefile.

The format of these directives parallels those in C, assembly language, and Turbo Pascal:

Note

!if expression

[ lines

!endif

!if expression

[ lines 1

!else

[ lines

!endif

!if expression

[ lines 1

!elif expression

[ lines

!endif

[lines]

can be any of the following statement types:

• macro_definition

• explicit_rule

• implicit_rule

• include_directive

.if~roup

• error_directive

• undef_directive

The conditional directives form a group, with at least an

!if

directive beginning the group and an

!endif

directive closing the group.

• One

!else

directive can appear in the group.

• !elif

directives can appear between the

!if

and any

!else

directives.

• Rules, macros, and other directives can appear between the various conditional directives in any number. Note that complete rules, with their commands, cannot be split across conditional directives.

• Conditional directive groups can be nested to any depth.

218

Borland C++ User's Guide

Chapter

Utilities

MAKE

Any rules, commands, or directives must be complete within a single source file.

All

!if

directives must have matching

!endif

directives within the same source file. Thus the following include file is illegal, regardless of what's in any file that might include it, because it doesn't have a matching

!endif

directive:

!if

(FILE_COUNT) > 5 some rules

!else other rules

<end-of-file>

Expressions allowed in conditional directives

Expressions are allowed in an

!if

or an

!elif

directive; they use a

C-like syntax. The expression is evaluated as a simple 32-bit signed integer.

You can enter numbers as decimal, octal, or hexadecimal constants. If you know the C language, you already know how to write constants in MAKE; the formats are exactly the same. If you program in assembly language or Turbo Pascal, be sure to look closely at the examples that follow. These are legal constants in a

MAKE expression:

4536 # decimal constant

0677 # octal constant (distinguished by leading 0)

Ox23aF # hexadecimal constant (distinguished by leading Ox)

An expression can use any of the following operators:

219

MAKE

Table 7.6

MAKE operators

Operator Operation

See

"Operator descriptions'

in Chapter 1 of the

Programmer's Guide for

complete descriptions of

these operators.

Unary operators

Negation

Bit complement

Logical NOT

Binary operators

+ Addition

Subtraction

Multiplication

Division

Remainder

Right shift

Left shift'

--

Bitwise AND

Bitwise OR

BitwiseXOR

Logical AND

Logical OR

Greater than

Less than

Greater than or equal

Less than or equal

Equality

Inequality

Ternary operator

? : Conditional expression

The operators have the same precedences as they do in the C language. Parentheses can be used to group operands in an expression. See the "Expressions" section in the

Programmer's

Guide.

You can invoke macros within an expression; the special macro

$d() is recognized. After all macros have been expanded, the expression must have proper syntax.

Error directive The error directive (!error) causes MAKE to stop and print a fatal diagnostic containing the text after !error.

It takes the format

!error

any_text

This directive is designed to be included in conditional directives to allow a user-defined error condition to abort MAKE. For example, you could insert the following code in front of the first explicit rule:

! if ! $d (MODEL)

# if MODEL is not defined

!error MODEL not defined

!endif

If you reach this spot without having defined MODEL, then

MAKE stops with this error message:

Fatal makefile 4: Error directive: MODEL not defined

220

Borland

C++

User's Guide

MAKE

Macro undefinitlon directive

The macro "undefinition" directive

(Iundef)

causes any definition for the named macro to be forgotten. If the macro is currently undefined, this directive has no effect. The syntax is

!undef

macro_name

MAKE errors

MAKE diagnostic messages fall into two classes: errors and fatal errors .

• Errors indicate some sort of syntax or semantic error in the source makefile .

• When a fatal error occurs, compilation immediately stops. You must take appropriate action and then restart the compilation.

The following generic names and values appear in the messages listed in this section. When you get an error message, the appropriate name or value is substituted.

In manual

argument(s) expression filename line number message

What you'll see onscreen

The command-line or other argument

An expression

A file name (with or without extension)

A line number

A message string

Messages are listed in ASCII alphabetic order; messages beginning with symbols come first. Since messages that begin with one of the variables just listed cannot be alphabetized by what you will actually see when you receive such a message, all such messages have been placed at the beginning of each error message list.

For example, if you have tried to link a file named NOEXIT.C, you might receive the following actual message: no exit does not exist--don't know how to make it

To look for this error, you would need to find

filename

does not exist-don't know how to make it

at the beginning of the list of error messages.

If the variable occurs later in the text of the error message (for example, "illegal character in constant expression:

expression"),

Chapter

Utilities

221

MAKE

222

Fatal error

you can find the explanation of the message in correct alphabetical order; in this case, under

filename does not exist - don't know how to make it

There's a nonexistent file name in the build sequence, and no rule exists that would allow the file name to be built.

Error

Bad file name format in include statement

Include file names must be surrounded by quotes or angle brackets. The file name was missing the opening quote or angle bracket.

Bad undef statement syntax

! undef

statement must contain a single identifier and nothing else as the body of the statement.

Error

Character constant too long

Character constants can be only one or two characters long.

Fatal error

Circular dependency exists in makefile

The makefile indicates that a file needs to be up-to-date BEFORE it can be built. Take, for example, the explicit rules:

filea: fileb fileb: filec filec: filea

This implies that filea depends on fileb, which depends on filec, and filec depends on filea. This is illegal, since a file cannot depend on itself, indirectly or directly.

Error

Command arguments too long

The arguments to a command were more than the 127-character limit imposed by DOS.

Command syntax error

This message occurs if

Error

• The first rule line of the makefile contained any leading whitespace.

• An implicit rille did not consist of

.ext.ext:.

• An explicit rule did not contain a name before the : character.

• A macro definition did not contain a name before the

= character.

Command too long

The length of a command has exceeded 128 characters. You might wish to use a response file.

Borland

C++ User's Guide

MAKE

Error

Fatal error

Division by zero

A divide or remainder in an

Iif

statement has a zero divisor.

Error directive: message

MAKE has processed an

#error

directive in the source file, and the text of the directive is displayed in the message.

Error

Illegal character in constant expression <expression>

MAKE encountered some character not allowed in a constant expression. If the character is a letter, this probably indicates a misspelled identifier.

Illegal octal digit

An octal constant was found containing a digit of 8 or 9.

Fatal error

Incorrect command-line argument: argument

You've used incorrect command-line arguments.

Error

Expression syntax error in !if statement

The expression in an

!if

statement is badly formed-it contains a mismatched parenthesis, an extra or missing operator, or a missing or extra constant.

File name too long

The file name in an

!include

directive is too long for the compiler to process. File names in DOS can be.no longer than 64 characters.

If statement too long

statement has exceeded 4,096 characters.

Error

Macro expansion too long

A macro cannot expand to more than 4,096 characters. This error often occurs if a macro recursively expands itself. A macro cannot legally expand to itself.

Misplaced elif statement

!elif

directive is missing a matching

!if

directive.

Misplaced else statement

There's an

!else

directive without any matching

!if

directive.

Error

Misplaced endif statement

There's an

!endif

directive without any matching

Iif

directive.

No file name ending

The file name in an include statement is missing the correct closing quote or angle bracket.

Chapter

Utilities 223

MAKE

Fatal error

Error

Fatal error

No terminator specified for in-line file operator

The makefile contains either the && or « command-line operators to start an in-line file, but the file is not terminated.

Not enough memory

All your working storage has been exhausted. You should perform your make on a machine with more memory. If you already have

640K in your machine, you may have to simplify the source file, or unload some memory-resident programs.

Redefinition of target filename

The named file occurs on the left side of more than one explicit rule.

Error

Fatal error

Rule line too long

An implicit or explicit rule was longer than 4,096 characters.

Unable to execute command

A command failed to execute; this may be because the command file could not be found, or because it was misspelled, or (less likely) because the command itself exists but has been corrupted.

Unable to open include file filename

The named file cannot be found. This can also be caused if an include file included itself. Check whether the named file exists.

Unable to open makefile

The current directory does not contain a file named

MAKEFILE, and there is no MAKEFILE.MAK.

Unable to redirect input or output

Make was unable to open the temporary files necessary to redirect input or output. If you are on a network, make sure you have rights to the current directory.

Error

Unexpected end of file in conditional started on line line number

The source file ended before MAKE encountered an !endif. The

!endif was either missing or misspelled.

Unknown preprocessor statement

A ! character was encountered at the beginning of a line, and the statement name following was not error, undef, if, elif, include, else, or endif.

224 Borland

C++

User's Guide

TUB

TLIB: The Turbo Librarian

TLIB is a utility that manages libraries of individual

.OBI

(object module) files. A library is a convenient tool for dealing with a collection of object modules as a single unit.

The libraries included with Borland C++ were built with TLIB.

You can use TLIB to build your own libraries, or to modify the

Borland C++ libraries, your own libraries, libraries furnished by other programmers, or commercial libraries you have purchased.

You can use TLIB to

• create

a new library from a group of object modules

• add object modules or other libraries to an existing library

• remove

object modules from an existing library

• replace

object modules from an existing library

• extract

object modules from an existing library

list

the contents of a new or existing library

When it modifies an existing library, TLIB always creates a copy of the original library with a .BAK extension.

TLIB can also create (and include in the library file) an Extended

Dictionary, which may be used to speed up linking. See the section on the IE option (page 229) for details.

Although TLIB is not essential to creating executable programs with Borland C++, it is a useful programmer productivity tool.

You will find TLIB indispensable for large development projects.

H you work with object module libraries developed by others, you can use TLIB to maintain those libraries when necessary.

Why use object module libraries?

When you program in C, you often create a collection of useful C functions, like the functions in the C run-time library. Because of

C's modularity, you are likely to split those functions into many separately compiled source files. You use only a subset of functions from the entire collection in any particular program. It can become quite tedious, however, to figure out exactly which files you are using. H you always include all the source files, on the other hand, your program becomes extremely large and unwieldy.

Chapter

Utilities

225

TUB

An object module library solves the problem of managing a collection of C functions. When you link your program with a library, the linker scans the library and automatically selects only those modules needed for the current program. In addition, a library consumes less disk space than a collection of object module files, especially if each of the object files is small. A library also speeds up the action of the linker, because it only opens a single file, instead of one file for each object module.

The TUB command line

Run TLIB by typing a TLIB command line at the DOS prompt. To get a summary of TLIB's usage, just type

TLIB and press

Enter.

The TLIB command line takes the following general form, where items listed in square brackets ([like this]) are optional: tlib libname [lC] [IE] [lPsize] [operations] [, lisifile]

This section summarizes each of these command-line components; the following sections provide details about using TLIB.

For examples of how to use TLIB, refer to the "Examples" section on page 231.

Table 7.7: TLiB options

Option

libname

IPsize operations listfile

Description

The DOS path name of the library you want to create or manage. Every TLIB command must be given a

libname.

Wildcards are not allowed. TLIB assumes an extension of .LIB if none is given. We recommend that you do not use an extension other than .LIB, since both BCC and BC's project-make facility require the .UB extension in order to recognize library files.

Note:

If the named library does not exist and there are add operations, TLIB creates the library.

The case-sensitive flag. This option is not normally used; see page 230 for a detailed explanation.

Create Extended Dictionary; see page 229 for a detailed explanation.

Set the library page size to

size;

see page 229 for a detailed explanation.

The list of operations TLIB performs. Operations may appear in any order. If you only want to examine the contents of the library, don't give any operations.

The name of the file listing library contents. The

listfile

name (if given) must be preceded by a comma.

If you do not give a file name, no listing is produced. The listing is an alphabetical list of each module. The entry for each module contains an alphabetical list of each public symbol defined in that module. The default extension for the

listfile

.LST.

You can direct the listing to the screen by using the

listfile

name CON, or to the printer by using the name PRN.

226

Borland C++ User's Guide

TLiB

The operation list The operation list describes what actions you want TLIB to do. It consists of a sequence of operations given one after the other.

Each operation consists of a one- or two-character

action symbol

followed by a file or module name. You can put whitespace around either the action symbol or the file or module name, but not in the middle of a two-character action or in a name.

You can put as many operations as you like on the command line, up to the DOS-imposed line-length limit of 127 characters. The order of the operations is not important. TLIB always applies the operations in a specific order:

1. All extract operations are done first.

2. All remove operations are done next.

3. All add operations are done last.

You can replace a module by first removing it, then adding the replacement module.

File and module names

TLIB finds the name of a module by taking the given file name and stripping any drive, path, and extension information from it.

(Typically, drive, path, and extension are not given.)

Note that TLIB always assumes reasonable defaults. For example, to add a module that has an .OBJ extension from the current directory, you only need to supply the module name, not the path and .OBJ extension.

Wildcards are never allowed in file or module names.

TLI B operations

TLIB recognizes three action symbols (-,

*), which you can use singly or combined in pairs for a total of five distinct operations.

For operations that use a pair of characters, the order of the characters is not important. The action symbols and what they do are listed here:

Chapter

Utilities

227

TLiB

Table 7.8

TLIB action symbols

To create

library, add modules to

library that does not yet exist.

You can't directly rename modules in rename

library. To

module, extract and remove it, rename the file just created, then add it back into the library.

Action symbol Name

Add

Description

TLIB adds the named file to the library. If the file has no extension given, TLIB assumes an extension of .OBJ. If the file is itself a library

(with a .LIB extension), then the operation adds all of the modules in the named library to the target library.

If a module being added already exists, TLIB displays a message and does not add the new module.

Remove

Extract

TLIB removes the named module from the library. If the module does not exist in the library, TLIB displays a message.

A remove operation only needs a module name.

TLIB allows you to enter a full path name with drive and extension included, but ignores everything except the module name.

TLIB creates the named file by copying the corresponding module from the library to the file.

If the module does not exist, TLIB displays a message and does not create a file. If the named file already exists, it is overwritten.

Extract & TLIB copies the named module to the

Remove corresponding file name and then removes it from the library. This is just a shorthand for an

extract

followed by a

remove

operation.

Replace TLIB replaces the named module with the cor-

+responding file. This is just a shorthand for a

remove

followed by an

add

operation.

Using response files

When you are dealing with a large number of operations, or if you find yourself repeating certain sets of operations over and over, you will probably want to start using

response files.

A response file is simply an ASCII text file (which can be created with the Borland C++ editor) that contains all or part of a TLIB command. Using response files, you can build TLIB commands larger than would fit on one DOS command line.

To use a response file

pathname,

specify @pathname at any position on the TLIB command line. Note that the DOS path length limitation is 128 characters.

228

Borland

C++

User's Guide

TLiB

• More than one line of text can make up a response file; you use the "and" character

(&) at the end of a line to indicate that another line follows.

• You don't need to put the entire TLIB command in the response file; the file can provide a portion of the TLIB command line, and you can type in the rest.

• You can use more than one response file in a single TLIB command line.

See "Examples" for a sample response file and a TLIB command line incorporating it.

Creating an extended dictionary: The

option

To speed up linking with large library files (such as the standard ex.LIB library), you can direct TLIB to create an

extended dictionary

and append it to the library file. This dictionary contains, in a very compact form, information that is not included in the standard library dictionary. This information enables TLINK to process library files faster, especially when they are located on a floppy disk or a slow hard disk. All the libraries on your distribution disks contain the extended dictionary.

To create an extended dictionary for a library that is being modified, use the IE option when you invoke TLIB to add, remove, or replace modules in the library. To create an extended dictionary for an existing library that you don't want to modify, use the IE option and ask TLIB to remove a nonexistent module from the library. TLIB will display a warning that the specified module was not found in the library, but it will also create an extended dictionary for the specified library. For example, enter tlib

IE

mylib -bogus

TLINK will ignore the debugging information in a library that has an extended dictionary, unless the

option is used on the TLINK command line.

Setting the page size: The /P option

Every DOS library file contains a dictionary (which appears at the end of the .LIB file, following all of the object modules). For each module in the library, this dictionary contains a 16-bit address of that particular module within the .LIB file; this address is given in terms of the library page size (it defaults to 16 bytes).

Chapter

Utilities

229

TUB

The library page size determines the maximum combined size of all object modules in the library-it cannot exceed 65,536 pages.

The default (and minimum) page size of 16 bytes allows a library of about 1 MB in size. To create a larger library, the page size must be increased using the

IP

option; the page size must be a power of

2, and it may not be smaller than 16 or larger than 32,768.

All modules in the library must start on a page boundary. For example, in a library with a page size of 32 (the lowest possible page size higher than the default 16), on the average 16 bytes will be lost per object modllle in padding. If you attempt to create a library that is too large for the given page size, TLIB will issue an error message and suggest that you use

IP

with the next available higher page size.

Advanced operation: The

option

When you add a module to a library, TLIB maintains a dictionary of all public symbols defined in the modules of the library. All symbols in the library must be distinct. If you try to add to the library a module that would cause a duplicate symbol, TLIB displays a message and won't add the module.

Normally, when TLIB checks for duplicate symbols in the library, uppercase and lowercase letters are not considered as distinct. For example, the symbols

lookup

and

LOOKUP

are treated as duplicates. Since C

does

treat uppercase and lowercase letters as distinct, use the

option to add a module to a library that includes a symbol differing

only in

case

from one already in the library. The

option tells TLIB to accept a module with symbols in it that differ only in case from symbols already in the library.

If you want to use the library with other linkers (or allow other people to use the library with other linkers), for your own protection you should not use the

Ie option.

It may seem odd that, without the

option, TLIB rejects symbols that differ only in case, especially since C is a case-sensitive language. The reason is that some linkers fail to distinguish between symbols in a library that differ only in case. Such linkers, for example, will treat

stars, Stars,

and

STARS

as the same identifier. TLINK, on the other hand, has no problem distinguishing uppercase and lowercase symbols, and it will properly accept a library containing symbols that differ only in case. In this example, then, Borland C++ would treat

stars, Stars,

and

STARS

as three separate identifiers. As long as you use the library only with TLINK, you can use the TLIB

option without any problems.

230

Borland

C++

User's Guide

TLiB

Examples

Here are some simple examples demonstrating the different things you can do with TLIB.

1. To create a library named MYLIB.LIB with modules X.OBJ,

Y.OBJ, and Z.OBJ, type tlib mylib +x +y +z

2. To create a library as in #1 and get a listing in MYLIB.LST too, type tlib mylib +x +y +z, mylib.lst

3. To get a listing in eS.LST of an existing library eS.LIB, type tlib cs, cs .lst

4. To replace module X.OBJ with a new copy, add A.OBJ and delete Z.OBJ from MYLIB.LIB, type tlib mylib -+x +a -z

5. To extract module Y.OBJ from MYLIB.LIB and get a listing in

MYLIB.LST, type tlib mylib *y, mylib.lst

6. To create a new library named ALPHA, with modules A.OBJ,

B.OBJ, ... , G.OBJ using a response file:

First create a text file, ALPHA.RSP, with

+a.obj +b.obj +c.obj &

+d.obj +e.obj +f.obj &

+g.obj

Then use the TLIB command, which produces a listing file named ALPHA.LST: tlib alpha @alpha.rsp, alpha. 1st

TLINK (linker)

The IDE has its own built-in linker. When you invoke the command-line compiler Bee or BeeX, TLINK (for Turbo Linker) is invoked automatically unless you suppress the linking stage.

If you suppress the linking stage, you must invoke TLINK manually. This section describes how to use TLINK or TLINKX

(protected mode version) as a standalone linker. At the end of this

Chapter

Utilities

231

TUNK

section, you will find a complete list of linker messages generated by TLINK and by the built-in IDE linker.

By default, the command-line compiler calls TLINK when compilation is successful; TLINK then combines object modules and library files to produce the executable file.

Invoking TLiNK

You can invoke TLINK at the DOS command line by typing tlink with or without parameters. When it is invoked without parameters, TLINK displays a summary of parameters and options. The following table briefly describes the TLINK options.

Note that this version of TLINK is sensitive to the case of its options;

is not the same option as

fT.

Table 7.9

TLINK options

You can use either a hyphen or a slash to precede TLlNK's commands.

Option

13

IA=nnnn

Ic

IC

Ie

Ii

In

Is

It

lTd

ITdc

ITde

ITw

ITwe

ITwd

lye

Iyx

What it does

Enable 32-bit processing.

Specify segment alignment for NewExe (Windows) images.

Treat case as significant in symbols.

Treat EXPORTS and IMPORTS section of module definition file as case sensitive.

Warn if duplicate symbols in libraries.

Ignore Extended Dictionary.

Initialize all segments.

Include source line numbers.

Specify library search paths.

Create map file with publics.

Don't use default libraries.

Overlay following modules or libraries.

Pack code segments.

Create detailed map of segments.

Generate .COM file. (Also

ITdc.)

Create target DOS executable.

Create target DOS .COM file.

Create target DOS .EXE file.

Create target Windows executable (.DLL or .EXE).

Create target Windows application (.EXE).

Create target Windows DLL (.DLL).

Include full symbolic debug information.

Don't create map file.

Use expanded memory for swapping.

Use extended memory for swapping.

The general syntax of a TLINK command line is

TLINK

objfiles, exefile, maPfi1e, libfiles, deffile

232

Borland

C++

User's Guide

TUNK

This syntax specifies that you supply file names

in the given order,

separating the file

types

with commas.

An example of linking for DOS

If you supply the TLINK command line tlink

Ie

mainline wd In tx,fin,mfin,work\lib\eomm work\lib\support

TLINK will interpret it to mean that

• Case is significant during linking

(/c).

The .OBJ files to be linked are MAINLINE.OBJ, WD.OBJ,

LN.OBJ, and TX.OBJ .

• The executable program name will be FIN.EXE. a The map file is MFIN.MAP .

.. The library files to be linked in are COMM.LIB and

SUPPORT. LIB, both of which are in subdirectory WORK\LIB.

No module definition file is specified.

An example of linking for Windows

To create a Windows application executable, you might use this command line: tlink

ITw Ie

\BORLANDC\lib\eOws winappl winapp2, winapp, winapp,

\BORLANDC\lib\cwins \BORLANDC\lib\es \BORLANDC\lib\import, winapp.def where

The

fTw

option tells TLINK to generate Windows executables.

The

option tells TLINK to be sensitive to case during linking.

Note that the EXPORTS and IMPORTS sections in the module definition file will be still treated as case-insensitive unless the

option is used.

\BORLANDC\LIB\COWS is the standard Windows initialization file and WINAPPI and WINAPP2 are the module's object files; for all three files the .OBJ extension is assumed.

WINAPP.EXE is the name of the target Windows executable.

III

WINAPP.MAP is the name of the map file.

\BORLANDC\LIB\CWINS is the small memory model runtime library for Windows, \BORLANDC\LIB\CS is the regular runtime library, and \ BORLANDC\ LIB \ IMPORT is the library that provides access to the built-in Windows functions .

• WINAPP.DEF is the Windows module definition file used to specify additional link options.

Chapter

Utilities

233

TUNK

File names on the TLiNK command line

If you don't specify an executable file name, TLINK derives the name of the executable by appending .EXE or .DLL to the first object file name listed.

If you specify a complete file name for the executable file, TLINK will create the file with that name, but the actual nature of that executable depends on other options or on settings in the module definition file. For instance, if you specify WINAPP.EXE, but you provide the

ITwd

option, the executable will be created as a DLL but named WINAPP.EXE-probably not what you intended.

Similarly, if you give WINAPP.DLL as the executable name, but include a lTd option on the command line, the file will be a DOS executable.

If no map file name is given, TLINK adds a .MAP extension to the

.EXE file name. If no libraries are included, none will be linked. If you don't specify a module definition (.DEF) file

and

you have used the

ITw

option, TLINK creates a Windows application based on default settings.

TLINK assumes or appends extensions to file names that have none:

• .OBJ for object files

• .EXE for executable files (when you use the

or the

ITde

optionJ

the executable file extension defaults to .COM rather than .EXE)

• .DLL for dynamic link libraries (when you use the /Twd option, or the /Tw option and the module definition file specifies a library)

• .MAP for map files

• .LIB for library files

• .DEF for module definition files.

All of the file names

except

object files are optional. So, for instance,

TLINK dosapp dosapp2 links the files DOSAPP.OBJ and DOSAPP2.0BJ, creates a DOS executable file called DOSAPP.EXE, creates a map file called

DOSAPP.MAP,links no libraries, and uses no module definition file.

234

Bor/and c++

User's Guide

TUNK

Using response files TLINK lets you supply the various parameters on the command line, in a response file, or in any combination of the two.

Because TLINK is now sensitive to the case of its options, you may need to modify response files, batch files, and makefiles intended for

previous version of

TLINK.

A response file is just a text file that contains the options and file names that you would usually type in after the name TLINK on your command line.

Unlike the command line, however, a response file can be continued onto several lines of text. You can break a long list of object or library files into several lines by ending one line with a plus character

(+) and continuing the list on the next line. When a plus occurs at the end of a line but it immediately follows one of the TLINK options that uses

+ to enable the option (such as

Iye+),

the

+ is not treated as a line continuation character.

You can also start each of the four components on separate lines: object files, executable file, map file, libraries. When you do this, you must leave out the comma used to separate components.

To illustrate these features, suppose that you rewrote the command line tlink

mainline wd In tx,fin,mfin,work\lib\eomm work\lib\support with the following response file, FINRESP:

mainline wd+

In tx,fin mfin work\lib\eomm work\lib\support

You would then enter your TLINK command as tlink @finresp

Note that you must precede the file name with an "at" character

(@) to indicate that the next name is a response file.

Alternately, you may break your link command into multiple response files. For example, you can break the previous command line into the following two response files:

Chapter

Utilities

235

TUNK

File name

LISTOBJS

LISTLIBS

Contents

mainline+ wd+

In tx lib\comm+ lib\support

You would then enter the TLINK command as tlink

@listobjs,fin,mfin,@listlibs

The TLiNK configuration file

The command line version of TLINK looks for a file called

TLINK.CFG first in the current directory, or in the directory from which it was loaded (DOS 3.0 or higher).

TLINK.CFG is a regular text file that contains a list of valid

TLINK options. Unlike a response file, TLINK.CFG can't list the groups of file names to be linked.

For instance, the following TLINK.CFG file

ILc:\BORLANDC\lib;c:\winapps\lib

Iv Is

ITw tells TLINK to search the specified directories for libraries, include debug information, create a detailed segment map, and produce a

Windows program.

Using TLiNK with

Borland C++ modules

Borland C++ supports six different memory models: tiny, small, compact, medium, large, and huge. When you create an executable Borland C++ file using TLINK, you must include the initialization module and libraries for the memory model being used.

The general format for linking Borland C++ programs with

TLINKis tlink CO[W I

D]x myobjs, exe,[map],

[IMPORT]

[mylibs]

[OVERLAY]

[CWINx]

[EMU I FP87 mathx]

Cx, [deffile]

where

myobjs exe

[map]

= the .OBJ files you want linked, specify path if not in current directory

= the name to be given the executable file

= the name to be given the map file (optional)

236

Borland

C++

User's Guide

TUNK

[mylibs]

deffile

= the library files you want included at link time

(optional), specify path if not in current directory, or use

option to specify search paths

= the module definition file for a Windows executable

If you are using the tiny model and you want TLINK to produce

.COM file, you must a/so specify the

/t or

/Tde option.

Be sure to include paths for the startup code and libraries (or use the

option to specify a list of search paths for startup and library files). The other file names on this general TLINK command line represent Borland C++ files, as follows:

COx

COFx

COW

CODx

IMPORT

OVERLAY

CWINx

EMU I FP87

MATHx

= initialization module for DOS executable, DOS executable written for another compiler, Windows application, or

Windows DLL (choose one) with memory model t (DOS only), s, c, m,

I, or h (DOS only)

Windows import library; the library that provides access to the built-in Windows functions

= overlay manager library; needed only for overlaid programs (not compatible with

Windows)

= run-time library for executable under Windows with memory model s, c, m, or I

= the floating-point libraries (choose one)

= math library for memory model s, c, m,

I, orh

= run-time library for memory model s, c, m, l,orh

Startup code

The initialization modules have the name

COx.OBJ, COWx.OBJ,

CODx.OBJ

(for DOS, a Windows application, and a Windows

DLL, respectively), where

x

is a single letter corresponding to the model: t for tiny (DOS only), s for small, c for compact, m for medium,

for large, and

for huge (DOS only).

Newl

The

COFx.OBJ

modules are provided for compatibility with source files intended for compilers from other vendors. The

COFx.OBJ

modules substitute for the

COx.OBJ

modules; they are to be linked with DOS applications only, not Windows applications or DLLs.

These initialization modules alter the memory model so that the stack segment is inside the data segment. The appropriate

Chapter

Utilities 237

TUNK

238

COFx.OBJ

module will be used automatically if you use either the

-Fs

or the

-Fm

command-line compiler option.

Failure to link in the correct initialization module usually results in a long list of error messages telling you that certain identifiers are unresolved, that no stack has been created, or that fixup overflows occurred.

The initialization module must also appear as the first object file in the list. The initialization module arranges the order of the various segments of the program. If it is not first, the program segments may not be placed in memory properly, causing some frustrating program bugs.

Be sure that you give an explicit name for the executable file name on the TLINK command line. Otherwise, your program name will be something like COx.EXE-probably not what you wanted!

Libraries

-.. The order of objects and libraries is very important. You must always put the Borland C++ start-up module

(COx.OBJ, COFx,

COWx.OBJ,

CODx.OBJ)

first in the list of objects. Then, the library list should contain, in this specific order:

• your own libraries

(if any)

• if you want to overlay your program (DOS only), you must include OVERLAY.LIB; this library must precede the Cx.LID library

• CWINx.LIB if you want your program to run under Windows

• if you are using floating point math, FP87.LIB or EMU. LIB

(required for DOS only), followed by MA THx.LIB (required for

DOS and Windows)

• Cx.LIB (Borland C++ run-time library file for DOS or Windows)

If you want to create a Windows application or DLL you must link IMPORT. LIB to provide access to the built-in Windows functions. IMPORT. LIB can be included anywhere in the list. If you are using any Borland C++ graphics functions, you must link in

GRA~HICS.LIB anywhere in the list. The graphics library is independent of memory models, but is for DOS only (not Windows).

If your program uses any floating-point, you must include a math library (MATHx.LIB) in the link command. For DOS applications

Borland

C++

User's Guide

TUNK

(but not for Windows applications or DLLs), you will also need to include either the EMU. LIB or FP87. LIB floating-point libraries.

Borland C++'s two floating-point libraries are independent of the program's memory model.

• Use EMU. LIB if you want to include floating-point emulation logic. With EMU. LIB the program will work on machines whether they have a math coprocessor (80x87) chip or not .

• If you know that the program will always be run on a machine with a math coprocessor chip, the FP87.LIB library will produce a smaller and faster executable program.

The math libraries have the name MA THx.LIB, where

x

is a single letter corresponding to the model: s, c, m,l, h (the tiny and small models share the library MA THS.LIB).

You can always include the emulator (DOS only) and math libraries in a link command line. If you do so, and if your program does no floating-point work, nothing from those libraries will be added to your executable program file. However, if you know there is no floating-point work in your program, you can save some time in your links by excluding those libraries from the command line.

You must always include the C run-time library for the program's memory model. The C run-time libraries have the name Cx.LIB, where

x

is a single letter corresponding to the model, as before.

Use the same C run-time library for both DOS and Windows executables.

If you aren't going to use all six memory models, and your hard disk space is limited, you may want to keep only the files for the model(s) you are using. Here's a list of the library files needed for each memory model (you'll also need FP87.LIB or EMU. LIB for

DOS only, and IMPORT.LIB for Windows):

Table 7.10

DOS application .OBJ and

.L1B files

Regular

Startup

Module

Compatibility

Startup

Module Model

Tiny

COT.OBJ

Small

COS.OBJ

Compact COCOBJ

Medium

Large

COM.OBJ

COL.OBJ

COFT.OBJ

COFS.OBJ

COFCOBJ

COFM.OBJ

COFL.OBJ

Huge COH.OBJ COFH.OBJ

Math

Library

MATHS.LIB

MATHCLIB

MATHM.LIB

MATHL.LIB

MATHH.LIB

Run-time

Library

CS.LIB

CCLIB

CM.LIB

CL.LIB

CH.LIB

Chapter

Utilities

239

TUNK

Table 7.11

Windows application .OBJ and

.L1B files

Model

Startup for Windows applications RTL

Small COWS.OBJ

CWINS.LIB

Compact

COWC.OBJ CWINC.LIB

Medium

Large

COWM.OBJ CWINM.LIB

COWL.OBJ

CWINL.LIB

Math

LibrarY

MATHS.LIB

MATHC.LIB

MATHM.LIB

MATHL.LIB

RTL

CS.LIB

CC.LIB

CM.LIB

CL.LIB

Note that the tiny and small models use the same libraries, but have different startup files (COT. OBI vs. COS.OBJ).

Table 7.12

DLL object and library files

Model

Small

Compact

Medium

Large

Startup for DLLs

Windows

RTL

CODS.OBJ CWINC.LIB

CODC.OBJ CWINC.LIB

CODM.OBJ CWINL.LIB

CODL.OBJ CWINL.LIB

Math

Library

MATHS.LIB

MATHC.UB

MATHM.LIB

MATHL.LIB

RTL

CS.LIB

CC.LIB

CM.LIB

CL.LIB

See Chapter 3, page 123 for more information on DLLs.

Using TLiNK with

Bee

See

Chapter 6, "The

command-line complier, " for

more on BCC.

You can also use BCC, the standalone Borland C++ compiler, as a

"front end" to TLINK that will invoke TLINK with the correct startup file, libraries, and executable program name.

To do this, you give file names on the BCC command line with explicit .OBI and .LIB extensions. For example, given the following BCC command line,

BCC -MX MAINFILE.OBJ SUB1.OBJ MYLIB.LIB

BCC will invoke TLINK with the files

COx.OBI,

EMU.LID,

MA THx.LIB and Cx.LIB (initialization module, default 8087 emulation library, math library and run-time library for memory model

x).

TLINK will link these along with your own modules

MAINLINE.OBI and SUB 1. OBI, and your own library MYLIB.LIB.

To compile and link a Windows program, include one of the

-W options on the compiler command-line, as well as any other options. The compiler will take care of linking in

COWx.OBI,

CWINx.LIB, and IMPORT.LIB.

When BCC invokes TLINK, it uses the

(case-sensitive link) option by default. You can override this default with -I-c).

240

Bor/and

C++

User's Guide

TUNK

TLiNK options

Importantl

TLINK options can occur anywhere on the command line. The options consist of a slash (/), a hyphen (-), or the DOS switch character, followed by the option. (The DOS switch character is

by default. You can change it by using an !NT 21H call.)

Starting with this version of TLINK, the case of an option is significant (/ t is not the same as

IT).

All options that existed before this version are lowercase. If you used uppercase options in response files or make files intended for a previous version of

TLINK, you'll need to modify those files before you use them with this version.

If you have more than one option, spaces are not significant

(Irnle

is the same as

1m Ie),

and you can have them appear in different places on the command line. The following sections describe each of the options.

The TLiNK configuration file

The command-line version of TLINK looks for a file called

TLINK.CFG first in the current directory, or in the directory from which it was loaded (DOS 3.0 or higher).

TLINK.CFG is a regular text file that contains a list of valid

TLINK options. Unlike a response file, TLINK.CFG can't list the groups of file names to be linked. Whitespace is ignored.

For instance, the following TLINK.CFG file

ILc: \ BORLANDC\lib;c: \winapps\lib

Iv Is

ITw tells TLINK to search the specified directories for libraries, include debug information, create a detailed segment map, and produce a

Windows program.

/3 (80386 32-bit code)

The

option should be used when one or more of the object modules linked has been produced by TASM or a compatible assembler, and contains 32-bit code for the 80386 processor. This option increases the memory requirements of TLINK and slows down linking, so it should be used only when necessary.

Chapter

Utilities 241

(align segments)

The

option specifies a byte value on which to align segments.

Segments smaller than the specified value will be padded up to the value. The syntax is

IA=nnnn

where nnnn is a number which respresents the alignment factor.

nnnn

must be a power of two. For instance,

/A=16 indicates that segments should be aligned on a paragraph boundary.

The default segment alignment size is 512. For efficiency, you should use the smallest value that still allows for correct segment offsets in the segment table. The file addresses in the segment table are multiplied by the alignment factor in order to be used as byte offsets into the executable file. Since the offsets are stored as

16-bit words, 65536 times the alignment factor is the limit of segment offsets that can be represented in the segment table. If you get this message, increase the segment alignment value.

c (case sensitivity)

The

option forces the case to be significant in public and external symbols.

(case sensitive exports)

By default, TLINK treats the EXPORTS and IMPORTS sections of the module definition file as case-insensitive. The

le+

option turns on case-sensitivity;

le-

turns off case-sensitivity.

(duplicate symbols)

Normally, TLINK will not warn you if a symbol appears in more than one library file. If the symbol must be included in the program, TLINK will use the copy of that symbol in the first file on the command line in which it is found. Since this is a commonly used feature, TLINK does not normally warn about the duplicate symbols. The following hypothetical situation illustrates how you might want to use this feature.

Suppose you have two libraries: one called SUPPORT. LIB, and a supplemental one called DEBUGSUP.LIB. Suppose also that

DEBUGSUP.LIB contains duplicates of some of the routines in

SUPPORT.LIB (but the duplicate routines in DEBUGSUP.LIB include slightly different functionality, such as debugging versions of the routines). If you include DEBUGSUP.LIB

first

in the link command, you will get the debugging routines and

not

the routines in SUPPORT. LIB.

242

Borland

C++

User's Guide

TUNK

If you are not using this feature or are not sure which routines are duplicated, you may include the

option. TLINK will list all symbols duplicated in libraries, even if those symbols are not going to be used in the program .

. Given this option, TLINK will also warn about symbols that appear both in an .OBJ and a .LIB file. In this case, since the symbol that appears in the first (left-most) file listed on the command line is the one linked in, the symbol in the .OBJ file is the one that will be used.

With Borland C++, the distributed libraries you would use in any given link command do not contain any duplicated symbols. So while EMU.LIB and FP87.LIB (or CS.LIB and CL.LIB) obviously have duplicate symbols, they would never rightfully be used together in a single link. There are no symbols duplicated between EMU. LIB, MATHS.LIB, and CS.LIB, for example.

/ e (no extended dictionary)

The library files that are shipped with Borland C++ all contain an

extended dictionary

with information that enables TLINK to link faster with those libraries. This extended dictionary can also be added to any other library file using the IE option with TLIB (see the section on TLIB starting on page 225). The TLINK

option disables the use of this dictionary.

Although linking with libraries that contain an extended dictionary is faster, you might want to use the

option if you have a program that needs slightly more memory to link when an extended dictionary is used.

Unless you use

to tum off extended dictionary use, TLINK will ignore any debugging information contained in a library that has an extended dictionary.

/i (uninitialized trailing segments)

The Ii option causes uninitialized trailing segments to be output into the executable file even if the segments do not contain data records. This option is not normally necessary.

/1 (line numbers) The

option creates a section in the .MAP file for source code line numbers. To use it, you must have created the .OBJ files by compiling with the -y (Line numbers ... On) or -v (Debug information) option. If you use the

to tell TLINK to create no map at all, this option will have no effect.

Chapter

Utilities

243

TUNK

/L (library search paths)

The

option lets you specify a list of directories that TLINK searches for libraries if an explicit path is not specified. TLINK searches the current directory before those specified with the

option. For example,

TLINK /Lc:\BORLANDC\lib;c:\mylibs splash logo",utils .\logolib

With this command line, TLINK first searches the current directory for UTILS.LIB, then searches C:\BORLANDC\LIB and

C: \MYLIBS. Because. \ LOGOLIB explicitly names the current directory, TLINK does not search the libraries specified with the

option to find LOGOLIB.LIB.

TLINK also searches for the C or c++ initialization module

(COx.OBJ, COWx.OBJ, CODx.OBJ)

on the specified library search path.

/m, /s, and /x (map options)

By default, TLINK always creates a map of the executable file.

This default map includes only the list of the segments in the program, the program start address, and any warning or error messages produced during the link.

If you don't want to create a map, turn it off with the

Ix

option.

If you want to create a more complete map, the

option will add a list of public symbols to the map file, sorted alphabetically as well as in increasing address order. This kind of map file is useful in debugging. Many debuggers can use the list of public symbols to allow you to refer to symbolic addresses when you are debugging.

The

option creates a map file with segments, public symbols and the program start address just like the

option did, but also adds a detailed segment map. The following is an example of a detailed segment map:

244

Borland C++ User's Guide

TUNK

Figure 7.1

Detailed map of segments

Address

Length Class Segment Name Group

(Bytes)

Module Alignment!

Combining

0000:0000 OE5B C=CODE S=SYMB TEXT

G=~none

M=SYMB.C ACBP=28

00E5:000B 2735 C=CODE S=QUALIEXT G= none M=QUAL.C ACBP=28

0359:0000 002B C=CODE S=SCOpV TEXT G=(none M=SCOPY ACBP=28

035B:000B 003A C=CODE S=LRSH TEXT

G=~none

M=LRSH ACBP=20

035F:0005 0083 C=CODE S=PADAIEXT G" none M=PADA ACBP=20

0367:0008 005B C=CODE S=PADDIEXT

GTOnel

M=PADD ACBP=20

036D:0003 0025 C=CODE S=PSBPIEXT

036F:0008 05CE C=CODE S=BRK TEXT

.. none~

M=PSBP

G= none M=BRK

ACBP=20

ACBP=28

03CC:0006 066F C=CODE S"FLOitr TEXT G" none M"FLOAT ACBP=20

0433:0006 OOOB C"DATA S= DATA-

0433:0012 00D3 C=DATA S=-DATA

G=DGROUP M=SYMB.(. ACBP"48

G=DGROUP M=QUAL.C ACBP=48

G=DGROUP M=BRK ACBP=48 0433:00E6 OOOE C=DATA S=-DATA

0442:0004 0004 C=BSS

S"-BSS

0442:0008 0002 C=BSS

S=-BSS

0442:000A OOOE C=BSS S=:BSS

G=DGROUP M=SYMB.C ACBP=48

G=DGROUP M=QUAL.C ACBP=48

G=DGROUP M=BRK ACBP=48

For each segment in each module, this map includes the address, length in bytes, class, segment name, group, module, and ACBP information.

If the same segment appears in more than one module, each module will appear as a separate line (for example, SYMB.C).

Except for the ACBP field, the information in the detailed segment map is self-explanatory.

The ACBP field encodes the A

(alignment),

(combination),

and B

(big)

attributes into a set of four bit fields, as defined by Intel.

TLINK uses only three of the fields, the A, C, and B fields. The

ACBP value in the map is printed in hexadecimal: The following values of the fields must be OR'ed together to arrive at the ACBP value printed.

Field Value

The A field

(alignment)

The C field 00

(combination)

The

B field

(big)

Description

An absolute segment.

A byte-aligned segment. word-aligned segment.

A paragraph-aligned segment.

A page-aligned segment.

An unnamed absolute portion of storage.

May not be combined.

A public combining segment.

Segment less than

64K.

Segment exactly

64K.

When you request a detailed map with the

option, the list of public symbols (if it appears) has public symbols flagged with

"idle" if there are no references to that symbol. For example, this fragment from the public symbol section of a map file indicates

Chapter

Utilities

245

TUNK

that symbols Symboll and Symbol3 are not referenced by the image being linked:

OC7F:031E idle

OOOO:3EA2

OC7F:0320 idle

Symbol

Symbol2

Symbo13

/n (ignore default libraries)

The

option causes the linker to ignore default libraries specified by some compilers. You may want to use this option when linking modules written in another language.

(overlays)

The b option causes the code in all modules or libraries specified after the option to be overlaid. It remains in effect until the next comma (explicit or implicit) or

in the command stream.

turns off overlaying. (Chapter 6, "Memory management," in the

Programmer's Guide

covers overlays in more detail.)

The

option can be optionally followed by a segment class name; this will cause all segments of that class to be overlaid. When no such name is specified, all segments of classes ending with CODE will be overlaid. Multiple

options can be given, thus overlaying segments of several classes; all

options remain in effect until the next comma or

is encountered.

The syntax

b#xx,

where

xx

is a two-digit hexadecimal number, overrides the overlay interrupt number, which by default is 3FH.

Here are some examples of

options:

Table 7.13

TLINK overlay options

Option Result

---------------------------------------------------

Overlay all code segments until next comma or

b-. b-

bOVY bCODEbOVLY

b#FO

Stop overlaying.

Overlay segments of class OVY until the next comma or b-.

Overlay segments of class CODE or class OVL Y until next comma or

b-.

Use interrupt vector OFOH for overlays.

If you use the

option, it will be turned off automatically before the libraries are processed. If you want to overlay a library, you must use another

right before all the libraries or right before the library you want to overlay.

246

Borland

C++

User's Guide

TUNK

You can't use the b option with any rrw option; Windows applications can't be overlaid. However, in order to achieve essentially the same results under Windows, use discardable code segments (see page 250 for information on defining code segments attributes in the module definition file).

(pack code segments)

When you use IP, when TLINK links Windows executables,

TLINK combines as many code segments as possible in one physical segment up to the code segment packing limit. Code segment packing never creates segments greater than this limit;

TLINK starts a new segment if it needs to.

The default code segment packing limit is 8,192 bytes (8K). To change it, use

/P==n

where

specifies the number of bytes between 1 and 65,536. You would probably want the limit to be a multiple of 4K under 386 enhanced mode.

Although the optimum segment size in 386 enhanced mode is 4K, the default code segment packing size is 8K. Because typical code segments are likely to be from 4K to 8K, an 8K packing size will probably result in more effective packing.

Because there is a certain amount of system overhead for every segment maintained, code segment packing, by reducing the number of segments to maintain, typically increases performance.

The IP option turns code packing on; it is off by default. IP- turns off code segment packing (useful if you've turned it on in the configuration file and want to disable it for a particular link).

It (tiny model

.COM file)

If you compile your file in the tiny memory model and link it with this option toggled on, TLINK will generate a .COM file instead of the usual .EXE file. Also, when you use

It,

the default extension for the executable file is .COM. This works the same as the rrde option. Neither

or rrde is compatible with the Windows option, rrw.

Note: .COM files may not exceed 64K in size, cannot have any segment-relative fixups, cannot define a stack segment, and must have a starting address equal to 0:100H. When an extension other than .COM is used for the executable file (.BIN, for example), the starting address may be either 0:0 or 0:100H.

Chapter

Utilities

247

TLiNK

TLINK can't generate debugging information for a .COM file. If you need to debug your program, create and debug it as an .EXE file, then relink it as a .COMfile. Alternatively, if you have Turbo

Debugger, you can use the TDSTRIP utility with the -c option; this creates a .COM file from and .EXE.

lTd

and

ITw

(target options)

These options are called target options. You use them (with c, e, or d) to produce a .COM, .EXE, or .DLL file .

• rrd creates a DOS .EXE file .

• rrdc creates a DOS .COM file.

• rrde creates a DOS .EXE file.

• rrw tells TLINK to create a Windows executable file. This option is not necessary if you include a module definition file with an EXETYPE Windows statement. With or without the rrw option, if the included module definition file h~s a NAME statement, TLINK creates an application

(.EXE)i

if the module definition file has a LIBRARY statement, TLINK creates a DLL.

If no module definition file is included in the link, you must specify the rrw or rrwe option for a Windows .EXE, or the rrwd option for a Windows DLL.

None of the rrw options are compatible with the 10 option

(overlay modules).

• rrwe creates Windows .EXE files. The rrwe option overrides a

LIBRARY statement in the module definition file (which normally causes TLINK to create a DLL).

• rrwd creates Windows DLLs. The rrwd option overrides a

NAME statement in the module definition file (which normally causes TLINK to create an .EXE file).

(debugging information)

The Iv option directs TLINK to include debugging information in the executable file. If this option is found anywhere on the command line, debugging information will be included executable for all object modules that contained debugging information. You can use the

Iv+

and

Iv-

options to selectively enable or disable inclusion of debugging information on a module-by-module basis (but not on the same command line as

Iv).

For example, this command tlink mod! /v+ mod2 mod3 /v- mod4 includes debugging information for modules

mod2

and

mod3,

but not for

modI

and

mod4.

248

Bor/and

c++

User's Guide

TUNK

TLINK can't generate debugging information for a .COM file (one created with the

or ITdc

options).

If you need to debug your program, create and debug it as an .EXE file, then relink it as a

.COM file. Alternatively, if you have Turbo Debugger, you can use the TDSTRIP utility with the --c option; this creates a .COM file from an .EXE.

(expanded or extended memory)

This option controls TLINK's use of expanded or extended memory for I/O buffering. If, while reading

~bject files or while writing the executable file, TLINK needs more memory for active data structures, it will either purge buffers or swap them to expanded or extended memory.

In the case of input file buffering, purging simply means throwing away the input buffer so that its space can be used for other data structures. In the case of output file buffering, purging means writing the buffer to its correct place in the executable file. In either case, you can substantially increase the speed of a link by allowing these buffers to be swapped to expanded or extended memory.

TLINK's capacity is not increased by swapping; only its performance is improved. By default, swapping to expanded memory is enabled, while swapping to extended memory is disabled.

If swapping is enabled and no appropriate memory exists in which to swap, then swapping does not occur. If you link with TLINKX, the protected mode linker, neither of these options has an effect.

This option has several forms, shown below

lye

or

Iye+

enable expanded memory swapping (default)

Iye-

disable expanded memory swapping

Iyx or /yx+

enable extended memory swapping

Iyx-

disable extended memory swapping (default)

Restrictions

Previous restrictions that no longer apply:

• TLINK now generates Windows .EXE and .DLL files.

• Common variables are now supported.

Segments that are of the same name and class that are uncombinable are now accepted. They aren't combined, and they appear separately in the map file.

• Any Microsoft code can now be linked with TLINK.

Chapter

Utilities

249

TUNK

TLINK can of course be used with Borland c++ (both the IDE and command-line versions), TASM, and other compilers.

The module definition file

The module definition file provides information to the linker about the contents and system requirements of a Windows application. More specifically, it

• names the application or dynamic link library (DLL)

• identifies the type of application as Windows or OS/2

• lists imported functions and exported functions

• describes the code and data segment attributes; allows you to specify attributes for additional code and data segments

• specifies the size of the heap and stack

• provides for the inclusion of a DOS stub program

Note that the IMPLIB utility can use a module definition file to create an import library (see page 192). The IMPDEF utility can actually create a module definition file for use with IMPLIB (see page 190).

Module definition file defaults

The module definition file is not strictly necessary to produce a

Windows executable under Borland C++.

If no module definition file is specified, the following defaults are assumed.

CODE

DATA

HEAPSIZE

STACKSIZE

PRELOAD MOVEABLE DISCARDABLE

PRELOAD MOVEABLE MULTIPLE (for applications) or PRELOAD MOVEABLE

SINGLE (for DLLs)

4096

5120

To replace the EXETYPE statement, the Borland C++ linker can discover what kind of executable you want to produce by checking settings in the IDE or options on the command line.

You can include an import library to substitute for the IMPORTS section of the module definition. .

You can use the _export keyword in the definitions of export functions in your C and c++ source code to remove the need for an EXPORTS section. Note, however, that if _export is used to

250

Borland

C++

User's Guide

TUNK

export a function, that function will be exported by name rather than by ordinal (ordinal is usually more efficient).

If you want to change various attributes from the default, you'll need to have a module definition file.

A quick example Here's a module definition from the WHELLO example, discussed on page 104:

NAME WHELLO

DESCRIPTION 'Ctt Windows Hello World'

EXETYPE

CODE

WINDOWS

MOVEABLE

DATA

HEAPSIZE

STACKSIZE

EXPORTS

MOVEABLE MULTIPLE

1024

5120

MainWindowProc

Let's take this file apart, statement by statement:

• NAME specifies a name for an application.

If you want to build a DLL instead of an application, you would use the LIBRARY statement instead. Every module definition file should have either a NAME statement or a LIBRARY statement, but never both. The name specified must be the same name as the executable file.

• DESCRIPTION lets you specify a string that describes your application or library.

• EXETYPE can be either WINDOWS or OS2. Only WINDOWS is supported in this version of Borland C++.

• CODE defines the default attributes of code segments. The

MOVEABLE option means that the code segment can be moved in memory at run-time.

• DATA defines the default attributes of data segments.

MOVEABLE means that it can be moved in memory at runtime. Windows lets you run more than one instance of an application at the same time. In support of that, the MULTIPLE options ensures that each instance of the application has its own data segment.

• HEAPSIZE specifies the size of the application's local heap.

• STACKSIZE specifies the size of the application's local stack.

You can't use the STACKSIZE statement to create a stack for a

DLL.

Chapter

Utilities

251

TUNK

• EXPORTS lists those functions in the WHELLO application that will be called by other applications or by Windows. Functions that are intended to be called by other modules are called callbacks, callback functions, or export functions .

• To help you avoid the necessity of creating and maintaining long EXPORTS sections, Borland C++ provides the _export keyword. Functions flagged with _export will be identified by the linker and entered into an export table for the module. If the

Smart Callbacks option is used at compile time (IWS on the

BCC command-line, or Options I Compiler I Entry /Exit Code I

Windows Smart Callbacks), then callback functions do

not

need to be listed either in the EXPORTS statement or flagged with the _export keyword. Borland C++ compiles them in such a way so that they can be callback functions.

This application doesn't have an IMPORTS statement, because the only functions it calls from other modules are those from the Windows API; those functions are imported via the automatic inclusion of the IMPORT.LIB import library. When an application needs to call other external functions, these functions must be listed in the IMPORTS statement, or included via an import library (see page 192 for a discussion of import libraries).

This application doesn't include a STUB statement. Borland C++ uses a built-in stub for Windows applications. The built-in stub simply checks to see if the application was loaded under Windows, and, if not, terminates the application with a message that

Windows is required. If you want to write and include a custom stub, specify the name of that stub with the STUB statement.

Module definition reference

This section describes each statement in a module definition file.

CODE

The CODE statement defines the default attributes of code segments. Code segments can have any name, but must belong to segment classes whose name ends in CODE. For instance, valid segment class names are CODE or MYCODE. The syntax is

CODE [FIXED

MOVEABLE]

[DISCARDABLE I NONDISCARDABLE]

[PRELOAD

LOADONCALL]

FIXED means that the segment remains at a fixed memory location; MOVEABLE means that the segment can be moved.

252

Borland

C++

User's Guide

Chapter

Utilities

TUNK

DISCARDABLE means that the segment can be discarded if it is no longer needed. DISCARDABLE implies MOVEABLE.

NONDISCARDABLE means that the segment can't be discarded.

PRELOAD means that the segment is loaded when the module is first loaded; LOADONCALL means that the segment is loaded when code in this segment is called. The Resource Compiler and the Windows loader set the code segment containing the initial program entry point to PRELOAD regardless of the setting in the module definition file.

Default attributes for code segments are

FIXED NONDISCARDABLE LOADONCALL

DATA

The DATA statement defines the default attributes of data segments.

The syntax of the DATA statement is

DATA [NONE

SINGLE

MULTIPLE] [FIXED

MOVEABLE]

NONE means that there is no data segment. If you specify NONE, do not include any other options. This option is available only for libraries.

SINGLE means that a single segment is shared by all instances of the module. MULTIPLE means that each instance of an application has a segment. SINGLE is only valid for libraries;

MULTIPLE is only valid for applications.

FIXED means that the segment remains at a fixed memory location. MOVEABLE means that the segment can be moved.

The default attributes for data segments in applications are FIXED

MULTIPLE. For libraries the default attributes are FIXED

SINGLE.

The automatic data segment is the segment whose group is

DGROUP. This physical segment also contains the local heap and stack (see the HEAPSIZE and STACKSIZE module definition file statements). The Resource Compiler and the Windows loader set the automatic data segment to be PRELOAD, regardless of the setting in the module definition file.

253

TUNK

254

DESCRIPTION

The DESCRIPTION statement inserts text into the application module. The DESCRIPTION statement is typically used to embed author, date, or copyright information. DESCRIPTION is an optional statement. The syntax is

DESCRIPTION ~Text'

Text

specifies an ASCII string delimited with single quotes.

EXElYPE The EXETYPE statement specifies the default executable file

(.EXE) header type (Windows or OS/2). You can only specify

WINDOWS in this version of Borland C++. The syntax is

EXETYPE

Type

determines the type of header TLINK writes to the executable file.

EXPORTS

The EXPORTS statement defines the names and attributes of the functions to be exported. The EXPORTS keyword marks the beginning of the definitions. It can be followed by any number of export definitions, each on a separate line. The syntax is

EXPORTS

ExportName [Ordinal]

[RESIDENTNAME] [NODATA]

[Parameter]

ExportName

specifies an ASCII string that defines the symbol to be exported. It has the following form:

<Entry Name>=[InternalName]

InternalName

is the name used within the application to refer to this entry.

EntryName

is the name listed in the executable file's entry table is externally visible.

Ordinal

defines the function's ordinal value. It has the following form:

@ordinal

where

ordinal

is an integer value that specifies the function's ordinal value.

When an application module or DLL module calls a function exported from a DLL, the calling module can refer to the function by name or by ordinal value. In term,s of speed, referring to the function by ordinal is faster since string comparisons are not required to locate the function.

In terms of memory allocation,

Borland

c++

User's Guide

TUNK

exporting a function by ordinal (from the point of view of that function's DLL) and imp orting/ calling a function by ordinal

(from the point of view of the calling module) is more efficient.

When a function is exported by ordinal, the name resides in the non-resident name table. When a function is exported by name, the name resides in the resident name table. The resident name table for a module is resident in memory whenever the module is loaded; the non-resident name table isn't.

The RESIDENlNAME option lets you specify that the function's name must be resident at all times. This is useful only when exporting by ordinal (when the name wouldn't be resident by default).

The NODATA option lets you specify that the function is not bound to a specific data segment. The function will use the current data segment.

Parameter

is an optional integer value that specifies the number of words the function expects to be passed as parameters.

HEAPSIZE

The HEAPSIZE statement defines the number of bytes needed by the application for its local heap. An application uses the local heap whenever it allocates local memory. The syntax is

HEAPSIZE

bytes bytes

is an integer value that specifies the heap size in bytes. It must not exceed 65,536 (the physical segment size).

The default heap size is zero. The minimum size is 256 bytes. The sum total of the automatic data segment (DGROUP), the local heap, and the stack must not exceed 65,536.

IMPORTS

The IMPORTS statement defines the names and attributes of the functions to be imported from dynamic link libraries. Instead of listing imported DLL functions in the IMPORTS statement, you can either specify an import library for the DLL in the TLINK command line, or-in the IDE-include the import library for the

DLL in the project.

The IMPORTS key word marks the beginning of the definitions. It can be followed by any number of import definitions, each on a separate line. The syntax is

IMPORTS

[InternaIName= ]ModuleName.Entry

Chapter

Utilities

255

TUNK

256

InternalName

is an ASCII string that specifies the unique name that the application will use to call the function.

ModuleName

specifies one or more uppercase ASCII characters that define the name of the executable module that contains the function. The module name must match the name of the executable file. For example, the file SAMPLE.DLL has the the module name SAMPLE.

Entry

specifies the function to be imported.

It can be either an

ASCII string that names the function, or an integer that gives the function's ordinal value.

LIBRARY The LIBRARY statement defines the name of a DLL module. A module definition file can contain either a NAME statement to indicate an application or a LIBRARY statement to indicate a DLL, but not both.

Like an application's module name, a library's module name must match the name of the executable file. For example, the library

MYLIB.DLL has the module name MYLIB. The syntax is

LIBRARY

LibraryName

specifies an ASCII string that defines the name of the library module.

The start address of the library module is determined by the library's object files; it is an internally defined function.

LibraryName

is optional. If the parameter is not included, TLINK uses the filename part of the executable file (that is, the name with the extension removed).

If the module definition file includes neither a NAME nor a

LIBRARY statement, TLINK assumes a NAME statement without a

ModuleName

parameter.

NAME The NAME statement defines the name of the application's executable module. The module name identifies the module when exporting functions. The syntax is

NAME

ModuleName

specifies one or more uppercase ASCII characters that define the name of the executable module. The module name must match the name of the executable file. For example, an

Borland C++ User's Guide

TUNK

application with the executable file SAMPLE.EXE has the module name "SAMPLE".

The

ModuleName

parameter is optional. If the parameter is not included, TLINK assumes that the module name matches the filename of the executable file. For example, if you do not specify a module name and the executable file is named MYAPP.EXE,

TLINK assumes that the module name is "MYAPP"

If the module definition file includes neither a NAME nor a

LIBRARY statement, TLINK assumes a NAME statement without a

ModuleName

parameter.

SEGMENTS The SEGMENTS statement defines the segment attributes of additional code and data segments. The syntax is

SEGMENTS

SegmentName

[CLASS ~ClassName']

[MinAlloc]

[FIXED I MOVEABLE] [DISCARDABLE I

NONDISCARDABLE]

[SHARED I NONSHARED] [PRELOAD I LOADONCALL]

SegmentName

specifies a character string that names the new segment. It can be any name, including the standard segment names _TEXT and _DATA, which represent the standard code and data segments.

ClassName

is an optional key word that specifies the class name of the specified segment. If no class name is specified, TLINK uses the class name CODE by default.

MinAlloc

is an optional integer value that specifies the minimum allocation size for the segment. Currently, TLINK ignores this value.

FIXED means that the segment remains at a fixed memory location. The MOVEABLE option means that the segment can be moved if necessary, in order to compact memory.

DISCARDABLE means that the segment can be discarded if it is no longer needed; NONDISCARDABLE means that the segment can not be discarded.

PRELOAD means that the segment is loaded immediately;

LOADONCALL means that the segment is loaded when it is accessed or called. The Resource Compiler may override the

LOADONCALL option and preload segments instead.

Chapter

Utilities

257

TUNK

Default attributes for additional segments are as described for

CODE and DATA segments (depending on the type of additional segment).

STACKSIZE The STACKSIZE statement defines the number of bytes needed by the application for its local stack. An application uses the local stack whenever it makes function calls. Do not use the ST ACK-

SIZE statement for dynamic link libraries. The syntax is

STACKSIZE

bytes bytes

is an integer value that specifies the stack size in bytes.

If the application makes no function calls, ST ACKSIZE defaults to o.

If your application does make function calls the minimum size is 5120 bytes (if you specify less, it will be changed to 5120). The sum total of the automatic data segment (DGROUP), the local heap, and the stack must not exceed 65,536.

STUB The STUB statement appends a DOS executable file specified by

FileName

to the beginning of the module. The executable stub should display a warning message and terminate if the user doesn't have Windows loaded.

Borland C++ adds a built-in stub to the beginning of a Windows application unless a different stub is specified with the STUB statement. Therefore, you should not use the STUB statement merely to include WINSTUB.EXE, because the linker will do this for you automatically.

The syntax is

STUB

"FileName"

FileName

specifies the name of the DOS executable file that will be appended to the module. The name must have the DOS file name format.

If the file named by

FileName

is not in the current directory,

TLINK searches for the file in the directories specified by the user's PATH environment variable.

TLINK

messages

TLINK has three types of messages: fatal errors, errors, and warnings.

258

Bor/and

C++

User's Guide

Chapter

Utilities

TUNK

• A fatal error causes TLINK to stop immediately; the .EXE file is deleted .

• An error (also called a nonfatal error) does not delete .EXE or

.MAP files, but you shouldn't try to execute the .EXE file. Errors are treated as fatal errors in the IDE .

.. Warnings are just that: warnings of conditions that you probably want to fix. When warnings occur, .EXE and .MAP files are still created.

The following generic names and values appear in the error messages listed in this section. When you get an error message, the appropriate name or value is substituted.

In manual

errorcode filename group linenum module segment symbol

XXXXh

What you'll see onscreen

Error code number for internal errors

A file name (with or without extension)

A group name

The line number within a file

A module name

A segment name

A symbol name

A 4-digit hexadecimal number, followed by

Warning

Messages are listed in

ASCII alphabetic order; messages beginning with variable names or numbers come first. Since messages that begin with one of the variables just listed cannot be alphabetized by what you will actually see when you receive such a message, all such messages have been placed at the beginning of the message list.

If the variable occurs later in the text of the error message (for example, "Invalid segment definition in module module"), you can find the message in correct alphabetical order; in this case, under

filename (linenum):

Duplicate external name in exports

Two export functions listed in the EXPORTS section of a module definition file defined the same external name. For instance,

EXPORTS

AnyProc=MyProcl

AnyProc=MyProc2

259

TUNK

260

Warning

filename (linenum): Duplicate internal name in exports

Two export functions listed in the EXPORTS section of the module definition file defined the same internal name. For example,

EXPORTS

JlnyProcl=~yProc

JlnyProc2=~yProc

filename (linenum): Duplicate internal name in imports

Two import functions listed in the IMPORTS section of the module definition file defined the same internal name. For instance,

IMPORTS

JlnyProc=~y~odl.~yProcl

JlnyProc=~y~od2.~yProc2 or

Fatal error

IMPORTS

~y~odl.~yProc

~y~od2.~yProc

filename (linenum):

File read error

A DOS error occurred while TLINK read the module definition file. This usually means that a premature end of file occurred.

Fatal error

filename (linenum):

Incompatible attribute

This error indicates that TLINK encountered incompatible segment attributes in a CODE or DATA statement (for instance, both PRELOAD and LOADONCALL can't be attributes for the same segment).

Fatal error

filename (Iinenum):

Missing internal name

In the IMPORTS section of the module definition file there was a reference to an entry specified via module name and ordinal number. When an entry is specified by ordinal number an internal name must be assigned to this import definition.

It is this internal name that your program uses to refer to the imported definition.

The syntax in the module definition file should be:

Fatal error

filename (Iinenum):

Syntax error

TLINK found a syntax error in the module definition file. The filename and line number tell you where the syntax error occurred.

Borland C++ User's Guide

TUNK

Warning

Error or Warning

symbol conflicts with module module in module module

This indicates an inconsistency in the definition of

symbol.

This either means that two virtual fllllctions of this name were encolllltered with different sizes, or that TLINK fOlllld one virtual fllllction and one command definition with the same name.

symbol is duplicated in module module

This message can result from a conflict between two symbols

(either public or commllllal) defined in the same module. An error occurs if both are encolllltered in an .OBJ file. A warning is issued if TLINK finds the duplicates in a library; in this case, TLINK uses the first definition ..

Error or Warning

symbol defined in module module is duplicated in module

module

This message can result from a conflict between two symbols

(either public or commllllal). This usually means that a symbol is defined in two modules. An error occurs if both are encolllltered in the .OBJ file(s), because TLINK doesn't know which is valid. A warning results if TLINK finds one of the duplicated symbols in a library and finds the other in an .OBJ file; in this case, TLINK uses the one in the .OBJ file.

Fatal error

32-bit record encountered

This message occurs when an object file that contains 80386 32-bit records is encolllltered, and the

option has not been used.

Simply restart TLINK with the

option.

Warning

Error

Attempt to export non-public symbol symbol

A symbol name was listed in the EXPORTS section of the module definition file, but no symbol of this name was fOlllld as public in the modules linked. This either implies a mistake in spelling or case, or that a procedure of this name was not defined.

Automatic data segment exceeds 64K

The sum of the DGROUP physical segment, local heap, and stack exceeded 64K. Either specify smaller values for the HEAPSIZE and STACKSIZE statements in the module definition file, or decrease the size of your near data in DGROUP. The map file will show the sizes of the component segments in

DGROUP. The

TLINK command-line option may be useful to help you find the module.

Chapter

Utilities 261

TUNK

262

Fatal error

Bad character in parameters

One of the following characters was encountered in the command line or in a response file:

I / * < = > ? [ ]

Fatal error

or any control character other than horizontal tab, line feed, carriage return, or

Ctr/-Z.

Bad object file filename

An ill-formed object file was encountered.

This is most commonly caused by naming a source file or by naming an object file that was not completely built. This can occur if the machine was rebooted during a compile, or if a compiler did not delete its output object file when a

Ctr/-Brk

was pressed.

Fatal error

Bad version number in parameter block

This error indicates an internal inconsistency in the IDE. If it occurs, exist and restart the IDE. This error will not occur in the standalone version.

Cannot generate COM file: data below initial CS:IP defined

This error results from trying to generate data or code below the starting address (usually 100) of a .COM file. Be sure that the starting address is set to 100 by using the (ORG 100H) instruction.

This error message should not occur for programs written in a high-level language. If it does, ensure that the correct startup

(COx)

object module is being linked in.

Cannot generate COM file: invalid

initi~1

entry point address

You used the

fTdc or It

option, but the program starting address is not equal to 100H, which is required with .COM files.

Cannot generate COM file: program exceeds 64K

You used the

fTdc or It

option, but the total program size exceeds the .COM file limit.

Fatal error

Error

Cannot generate COM file: segment-relocatable items present

You used the

rrdc or It

option, but the program contains segment-relative fixups, which are not allowed with .COM files.

Cannot generate COM file: stack segment present

You used the

fTdc or It

option, but the program declares a stack segment, which is not allowed with .COM files.

Common segment exceeds 64K

The program had more than 64K of near uninitialized data.

Try declaring some uninitiallzed data as far.

Borland C++ User's Guide

Chapter

Utilities

TLiNK

Warning

Fatal error

Warning

Error

Debug info switch ignored for .COM files

Borland C++ does not include debug information for .COM files.

See the description of the

option on page 248.

DOS error, ax

number

This occurs if a DOS call returned an unexpected error. The

value printed is the resulting error code. This could indicate a

TLINK internal error or a DOS error. The only DOS calls TLINK makes where this error could occur are read, write, seek, and close.

Duplicate ordinal

number

in exports

This warning occurs when TLINK encounters two exports with the same ordinal value. First check the module definition file to ensure that there are no duplicate ordinal values specified in the

EXPORTS section.

If not, then you are linking with modules which specify exports by ordinals and one of two things happened: either two export records specify the same ordinal, or the exports section in the module definition file duplicates an ordinal in an export record.

Export records (EXPDEF) are comment records found in object files and libraries which specify that particular variables are to be exported. Optionally, these records can specify ordinal values when exporting by ordinal (rather than by name).

Fixup overflow at

segment:xxxxh,

target

segment:xxxh

in module

module

Fixup overflow at

segment:xxxxh,

target

symbol

in module

module

Either of these messages indicate an incorrect data or code reference in an object file that TLINK must fix up at link time.

This message is most often caused by a mismatch of memory models. A

near

call to a function in a different code segment is the most likely cause. This error can also result if you generate a

near

call to a data variable or a data reference to a filllction. In either case the symbol named as the

target

in the error message is the referenced variable or function. The reference is in the named module, so look in the source file of that module for the offending reference.

In an assembly language program, a fixup overflow frequently occurs if you have declared an external variable within a segment definition, but this variable actually exists in a different segment.

263

TUNK

264

If this technique does not identify the cause of the failure, or if you are programming in assembly language or a high-level language besides Borland C++, there may be other possible causes for this message. Even in Borland C++, this message could be generated if you are using different segment or group names than the default values for a given memory model.

Fatal error

Group group exceeds 64K

This message will occur if a group exceeds 64K bytes when the segments of the group are combined.

Warning

Fatal error

Group group1 overlaps group group2

This means that TLINK has encountered nested groups. This warning only occurs when overlays are used or when linking a

Windows program.

Illegal group definition: group in module module

This error results from a malformed GRPDEF record in an .OB} file. This latter case could result from custom-built .OB} files or a bug in the translator used to generate the .OB} file. If this occurs in a file created by Borland C++, recompile the file. If the error persists, contact Borland.

Fatal error

Fnta/ error

Internal linker error errorcode

An error occurred in the intemallogic of TLINK.

This error shouldn't occur in practice, but is listed here for completeness in the event that a more specific error isn't generated. If this error persists, write down the

errorcode

number and contact Borland.

Internal undefined error

An error occurred in the internal logic of TLINK. This error shouldn't occur in practice, but is lis~ed here for completeness in the event that a more specific error isn't generated.

If this error persists, contact Borland.

Warning

Invalid entry at segment:xxxxh

A rare internal error of TLINK, listed here for completeness. This error indicates that a necessary entry was missing from the entry table of a Windows executable file. If it persists, contact Borland.

Error

Invalid entry point offset

This message occurs only when modules with 32-bit records are linked.

It means that the initial program entry point offset exceeds the DOS limit of

64K.

Borland

c++

User's Guide

Chapter

Utilities

TUNK

Fatal error

Invalid initial stack offset

This message occurs only when modules with 32-bit records are linked. It means that the initial stack pointer value exceeds the

DOS limit of

64K.

Fatal error

Invalid limit specified for code segment packing

This error occurs if you used the

option and specified a size limit that was out of range. To be valid, the size limit must be between 1 and 65536 bytes; the default is 4096.

Invalid segment definition in module

module

This message will generally occur only if a compiler produced a flawed object file. If this occurs in a file created by Borland C++, recompile the file.

If the problem persists, contact Borland.

Error

Warning

Invalid size specified for segment alignment

This error occurs if an invalid value is specified for the fA option.

The size specified with fA must be an integral multiple of 2 and less than

64K.

Common values are 16 and 512. This error only occurs when linking for Windows.

No automatic data segment

No group named DGROUP was found. Because the Borland C++ initialization files define DGROUP, you will only see this error if you don't link with an initialization file and your program doesn't define DGROUP. Windows uses DGROUP to find the local data segment. The DGROUP is required for Windows applications (but not DLLs) unless DATA NONE is specified in the module definition file.

Warning

No module definition file specified: using defaults

TLINK was invoked with one of the Windows options, but no module definition file was specified. See page 250 for more information about module definition file defaults.

Warning

No program starting address defined

This warning means that no module defined the initial starting address of the program. This is almost certainly caused by forgetting to link in the initialization module

COx.OBJ.

This warning should not occur when linking a Windows DLL.

No stack

This warning is issued if no stack segment is defined in any of the object files or in any of the libraries included in the link. This is a normal message for the tiny memory model in Borland C++, or

265

TUNK

for any application program that will be converted to a .COM file.

For other programs (except DLLs), this indicates an error.

If a Borland C++ program produces this message for any but the tiny memory model, make sure you are using the correct

COx

startup object files.

Warning

Fatal error

No stub for fixup at

segmentxxxxh

in module

module

This error occurs when the target for a fixup is in an overlay segment, but no stub is found for a target external. This is usually the result of not making public a symbol in an overlay that is referenced from the same module.

Not enough memory

There is not enough memory to run TLINK. Try removing any

TSR applications currently loaded, or reduce the size of any RAM disk currently active. Then run TLINK again.

Fatal error

Out of memory

TLINK has run out of dynamically allocated memory needed during the link process. This error is a catchall for running into a

TLINK limit on memory usage. This usually means that too many modules, externals, groups, or segments have been defined by the object files being linked together.

Warning

Error

Overlays generated and no overlay manager included

This warning is issued if overlays are created but the symbol

__ OVRTRAP __ is not defined in any of the object modules or libraries linked in. The standard overlay library (OVERLAY.LIB) defines this symbol.

Overlays ignored in new executable image

This error occurs if you attempt to link a Windows program with the b option on. Windows executables can't be overlaid, although, with discardable code segments, you should be able to achieve a similar effect.

Program entry point may not reside

,in

an overlay

Although almost all of an application can be overlaid, the initial starting address cannot reside in an overlay. This error usually means that an attempt was made to overlay the initialization module

COx.OBJ,

for instance, by specifying the

option before the startup module.

266 Borland

C++

User's Guide

TUNK

Fatal error

Relocation item exceeds 1 MB DOS limit

The DOS executable file format doesn't support relocation items for locations exceeding 1MB. Although DOS could never load an image this big, DOS extenders can, and thus TLINK supports generating images greater than DOS could load. Even if the image is loaded with a DOS extender, the DOS executable file format is limited to describing relocation items in the first 1MB of the image.

Fatal error

Relocation offset overflow

This error only occurs for 32-bit object modules and indicates a relocation (segment fixup) offset greater than the DOS limit of

64K.

Fatal error

Relocation table overflow

This error only occurs for 32 bit object modules. The file being linked contains more base fixups than the standard DOS relocation table can hold (base fixups are created mostly by calls to far functions).

Fatal error

Segment segment exceeds 64K

This message occurs if too much data is defined for a given data or code segment when TLINK combines segments with the same name from different source files.

Warning

Fatal error

Segment segment is in two groups: group1 and group2

The linker found conflicting claims by the two named groups.

Usually, this only happens in assembly language programs. It means that two modules assigned the segment to two different groups.

Segment alignment factor too small

This error occurs if the segment alignment factor (set with the

fA

option) is too small to represent the file addresses of the segments in the .EXE file. This error only occurs when linking for Windows.

See the documentation for the

fA

option on page 242 for more information.

Fatal error

Segment too large for segment table

This error should never occur in practice. It means that a segment was bigger than 64K and its size cannot be represented in the executable file. This error can only occur when linking for Windows; the format of the executable file used for Windows does not support segments greater than

64K.

Chapter

Utilities 267

TUNK

Fatal error

Stub program exceeds 64K

This error occurs if a DOS stub program written for a Windows application exceeds 641<. Stub programs are specified via the

STUB module definition file statement. TLINK only supports stub programs up to

64K.

Fatal error

Table limit exceeded

This message results 'from one of linker's internal tables overflowing. This usually means that the programs being linked have exceeded the linker's capacity for public symbols, external symbols, or for logical segment definitions. Each instance of a distinct segment name in an object file counts as a logical segment; if two object files define this segment, then this results in two logical segments

Error

Too many error or warning messages

On the command line or in the IDE, you can set a limit on the number of errors or warnings that can occur before linking is stopped. This error indicates that TLINK reached that limit.

Fatal error

Unable to open file filename

This occurs if the named file does not exist or is misspelled.

Error

Undefined symbol symbol in module module

The named symbol is referenced in the given module but is not defined anywhere in the set of object files and libraries included in the link. Check to make sure the symbol is spelled correctly.

Fatal error

Error

You will usually see this error from TLINK for Borland C++ symbols if you did not properly match a symbol's declarations of

pascal and cdecl

type in different source files, or if you have omitted the name of an .OBJ file your program needs. If you are linking C++ code with C modules, you might have forgotten to wrap C external declarations in

extern

"e" { ... }.

Unknown option

A forward slash character (/), hyphen (-), or DOS switch character was encountered on the command line or in a response file without being followed by one of the allowed options. This might mean that you used the wrong case to specify an option.

User break

TLINK aborts linking when the

etrl-Break

key is pressed.

268 Borland

C++

User's Guide

TUNK

Fatal error

Write failed, disk full?

This occurs if

TLINK could not write all of the data it attempted to write. This is almost certainly caused by the disk being full.

Chapter

Utilities 269

270

Borland

C++

User's Guide

A p p

E N D x

Precompiled headers

Borland c++ can generate and subsequently use precompiled headers for your projects. Precompiled headers can greatly speed up compilation times.

How they work

When compiling large C and c++ programs, the compiler can spend up to half of its time parsing header files. When the compiler parses a header file, it enters declarations and definitions into its symbol table. If ten of your source files include the same header file, this header file is parsed ten times, producing the same symbol table every time.

Precompiled header files cut this process short. During one compilation, the compiler stores an image of the symbol table on disk in a file called TCDEF.SYM by default. (TCDEF.SYM is stored in the same directory as the compiler.)Later, when the same source file is compiled again (or another source file that includes the same header files), the compiler reloads TCDEF.SYM from disk instead of parsing all the header files again. Directly loading the symbol table from disk is over ten times faster than parsing the text of the header files.

Precompiled headers will only be used if the second compilation uses one or more of the same header files as the first one, and if a

Appendix

Precompiled headers

271

lot of other things, like compiler options, defined macros and so on, are also identical.

If, while compiling a source file, Borland C++ discovers that the first #includes are identical to those of a previous compilation (of the same source or a different source), it will load the binary image for those #includes, and parse the remaining #includes.

Use of precompiled headers for a given module is an all or nothing deal: the precompiled header file is not updated for that module if compilation of any included header file fails.

Drawbacks

When using using precompiled headers, TCDEF.SYM can become very big, because it contains symbol table images for all sets of includes encountered in your sources. You can reduce the size of this file; see "Optimizations" on page 274.

If a header contains any code, then it can't be precompiled. For example, while C++ class definitions may appear in header files, you should take care that only member functions that are inline are defined in the header; heed warnings such as "Functions containing for are not expanded inline".

USing precompiled headers

You can control the use of precompiled headers in any of three ways:

• from within the IDE, using the Options I Compiler I Code

Generation dialog box (see page 62). The IDE bases the name of the precompiled header file on the project name, creating

PRO]ECT.5YM

• from the command line using the -H,

-H=filename,

and -Hu options (see page 178)

• or from within your code using the pragmas hdrfile and hdrstop (see Chapter 4 in the

Programmer's Guide)

272

Borland C++ User's Guide

Setting file names

Caution/

The compiler uses just one file to store all precompiled headers.

The default file name is TCDEF.SYM. You can explicitly set the name with the

-H=filename

command-line option or the

#pragma hdrfile directive.

You may notice that your .SYM file is smaller than it should be. If this happens, the compiler may have run out of disk space when writing to the .SYM file. When this happens, the compiler deletes the .SYM in order to make room for the .OBI file, then starts creating a new (and therefore shorter) .SYM file. If this happens, just free up some disk space before compiling.

Establishing identity

The following conditions need to be identical in order for a previously generated precompiled header to be loaded for a subsequent compilation.

The second or later source file must:

II have the same set of include files in the same order

• have the same macros defined to identical values

• use the same language (C or C++)

• use header files with identical time stamps; these header files can be included either directly or indirectly

In addition, the subsequent source file must be compiled with the same settings for the following options:

• memory model, including SS != DS

(-mx)

II underscores on extems

(-u)

• maximum identifier length (-iL)

• target DOS (default) or Windows

(-W or -Wx)

• generate word alignment (-a)

• Pascal calls (-p)

• treat enums as integers (-b)

• default char is unsigned (-K)

• virtual table control (-V

Appendix

Precompiled headers

273

274

Optimizing precompiled headers

For Borland c++ to most efficiently compile using precompiled headers, follow these rules:

• Arrange your header files in the same sequence in all source files.

• Put the largest header files first.

• Prime TCDEF.SYM with often-used initial sequences of header files.

• Use

#pragma hdrstop

to terminate the list of header files at well-chosen places. This lets you make the list of header files in different sources look similar to the compiler.

#pragma hdrstop

is described in more detail in Chapter 4 in the

Programmer's

Guide.

For example, given the two source files ASQURCE.C and

BSQURCE.C, both of which include windows.h and myhdr.h,

ASOURCE.C:

tinclude <windows.h>

*include "myhdr.h"

*include "xxx.h"

< ...

BSOURCE.C:

*include "zz.h" tinclude <string.h>

*include "myhdr.h" tinclude <windows.h>

< ... >

You would rearrange the beginning of BSQURCE.C to:

Revised BSOURCE.C:

tinclude <windows.h>

*include "myhdr.h"

*include "zz.h" tinclude <string.h>

< ..• >

Note that windows.h and myhdr.h are in the same order in

BSQURCE.C as they are in ASQURCE.C. You could also make a new source called PREFIX.C containing only the header files, like this:

PREFIX.C

tinclude <windows.h>

#include "myhdr.h"

Borland C++ User's Guide

If you compile PREFIX.C first (or insert a

#pragrna hdrstop in both

ASOURCE.C and BSOURCE.C after the

#include "myhdr.h" statement) the net effect is that after the initial compilation of

PREFIX.C, both ASOURCE.C and BSOURCE.C will be able to load the symbol table produced by PREFIX.C. The compiler will then only need to parse xxx.h for ASOURCE.C and zz.h and string.h for BSOURCE.C.

Appendix A, Precompiled headers

275

276

Borland

C++

User's Guide

N D E x

43/50-line display 91

- + and

+ -

(TUB action symbols) 228

<> (angle brackets) in #include directive 89

$* (base file name macro) 214

-2 BCC option (80286 instructions) 167

-1 BCC option (extended 80186 instructions)

167

(chevron) in dialog boxes 18

$. (file name and extension macro) 215

$& (file name only macro) 215

$: (file name path macro) 215

$< (full file name macro) 214

MAKE help opt~on 197

-1 option (extended 80186 instructions)

See also

80186 processor, generating extended instructions

/3 TUNK option (32-bit code) 241

-* and *- (TLIB action symbols) 228

32-bit code 241

- (hyphen) MAKE command (ignore exit status)

202

25-line display 91

(MAKE comment character) 201

386

MAX

&&operator

MAKE 202, 203

« operator

MAKE 202

» operator

MAKE

202

-? RC help option 122

; (semicolons) in directory path names

:: (System) menu 8

- (tilde) in transfer program names 75

* (TLIB action symbol) 228

(TLIB action symbol) 228

- (TLIB action symbol) 228

$ editor macros See individual names of macros; transfer macros

MAKE command 202

80x87 math coprocessors See numeric coprocessors

80x86 processors

32-bit code 241 instruction set 63 instructions 167 extended 167

:: (System) menu 8, 26

~ (arrows) in dialog boxes 17

/P TLINK option (pack code segments)need index 247

-a BCC option (align integers) 167

-A BCC option (ANSI keywords) 174

-a MAKE option (autodependency check) 197,

208

About command 27

ACBP field 245 action symbols

See TLIB (librarian) activating menu bar 9 active window See windows, active add (TLIB action symbol) 228

Add button 58

Add Item command 58,

133

Add Item to Project List dialog box 58

Add Watch command 54 hot key 12

Advanced Code Generation dialog box

63 alignment attribute 245 integers 167 word 61

American National Standards Institute

See

ANSI angle brackets

«»

in #include directive 89

Index

277

ANSI

Borland C++ keywords and 174 compatible code 174 floating point conversion rules 169 keywords option 174 using only

violations 175

ANSI Violations 71, 72 applications

Microsoft Windows

See

Microsoft Windows applications transferring to and from Borland C++ 74

Arguments command 44 dialog box 44 arguments command-line compiler 158 variable list

170

arrays huge fast huge pointer arithmetic and 64 arrays, inspecting values 49 arrows

(~) in dialog boxes 17

.ASM files

See

assembly language assembly language assembling from the command line 157 compiling 178 default assembler 178 directory 184 inline routines 178 options passing 179 removing 179 output files 179 projects and 138 assembly level debugger

See

Turbo Debugger

Assume SS equals DS option 62

-AT BeC option (Borland C++ keywords) 174 attributes

ACBP 245 alignment 245 big 245 combining 245

-AU option (UNIX keywords) 174

Auto Save option 91 auto variables

See

variables, automatic

278

.autodepend MAKE directive 216 autodependencies

See also

dependencies explicit dependencies and 78

Autoindent Mode option 92 automatic dependencies 83 checking 138

MAKE (program manager) 197,

208

information disabling 171

MAKE option 216

Automatic Far Objects option 64 automatic variables

See

variables, automatic

-b BCC option (allocate whole word for enums)

168

-B BCC option (process inline assembler code)

178

/b IDE option (build) 5

-B MAKE option (build all) 197

Backspace Unindents option 92 backup files (.BAK) 92 backward pair matching 153 searching

.BAK files 92 bar, title 14 base file name macro (MAKE) 214 batch files, MAKE

203, 204

BBS segment

~ee

also

segments

BC.EXE

See

integrated environment

BCC.EXE

BCINST

See

command-line compiler

See also

BCINST menu and command names

BGI

See

Borland Graphics Interface

BGIOBJ

See

The online document VTIL.DOC big attribute 245 block operations (editor) operations

Borland C++

See

editing, block

C and

170

calling convention 66 keywords as identifiers

70,

174 project files and 138 quitting 8, 33 starting up 4

Borland

C++

User's Guide

transferring from 74

Borland Graphics Interface (BGI) graphics

EGA palettes and 7

See also

library 84

Borland c++

See also

C++; C language; keywords boxes

See

check boxes; dialog boxes; list boxes; text, boxes

Break Make On menu 136 option 83

Breakpoints command 55 dialog box 55 breakpoints

See also

debugging; watch expressions clearing 56 controlling 55 deleting 55 editing 55 inline functions and 68 losing 56 saving across sessions 94 setting 55 viewing 55

. BSS names 73 bugs

See

debugging

Build All command 46 build IDE option 5

BUILTINS.MAK 196 buttons

Change 152

Change All 39, 152 choosing 17 in dialog boxes 17 mouse 94 radio 18 c

C++ 67, classes

See also

C language; Borland C++

See

classes compiling 67 compiling files as 179

DLLs and 127 functions inline command-line option (-vi) 172 debugging and 67, 172 virtual tables and 182 help

100

virtual tables command 67

See

warnings 72, 176 c++ Options virtual tables dialog box 67

C++ Warnings dialog box 72

-c

BCC option (compile but don't link) 178

-C BCC option (nested comments) 174

IC

TLIB option (case sensitivity) 226,

230

IC

TLINK option (case sensitive imports) 242

Ic

TLINK option (case sensitivity) 242

COFx.OBJ 237

C language

See also

C++

Borland C++ and

170

help

100

COx. OBI

237

Call Stack command 51 hot key 12 callbacks smart

See

smart callbacks memory models and 66

Windows applications and 66 calling conventions 66

Cancel button 17

$CAP EDIT macro 75

$CAP EDIT transfer macro 77

$CAP MSG transfer macro 77

Cascade command 96

Case-Sensitive Exports option 85 case sensitivity in searches 37 linking with 85 module definition file and 85,242

TLIB option 226,

230

TLINK and 241,242 cdec1 statement

170

.CFG files

See

configuration files

Change All button 39, 152

Change button 152

Index

279

Change Dir command

Change Directory dialog box 31 characters control

IDE and 18 data type char

See

data types, char tab printing 31

Check Auto-dependencies option 83 check boxes 18 chevron symbol (») 18

Class Inspector window 50 classes debugging 50

DLLsand 127, 191 inspecting 49 names 73 sharing objects 68, 183

Clear command 36, 149 hot key 11

Clear Desktop command 27 click speed (mouse) 94

Clipboard 34 clearing 36 editing text in 36 saving across sessions 94 showing 36 close boxes 14

Close command 96 hot key 12

Close Project command 58

Code Generation command 61 dialog box 61, 63 code generation command-line compiler options 167

Code Pack Size option 85 code segment discard able 246 group 177 names 73 naming and renaming 177 default 178 storing virtual tables in 68, 182

-WD option and 113,

180

$COL transfer macro 77

280 colors and palettes

EGA 7 columns numbers 13, 77

.COMfiles generating 237

TUNK247 limitations 247 size 247 combining attribute 245

COMDEFs generating 168

PUBDEFs versus 64 command line

Borland C++

See

command-line compiler options

See

command-line compiler, options; integrated environment, command-line options viewing from IDE 97 command-line compiler arguments 158 compiling and linking with 158

Windowsapplications

108

configuration files

See

configuration files,

BCC

DLLs and 123

MAKE and 216 options

160, 165

-2 (80286 instructions) 167

80286 instructions (-2) 167

-1

(extended

80186 instructions) 167

-A and -AT (Borland C++ keywords) 174

-H

(precompiled headers) 178

-0 Gump optimization) 172

-p (C++ and C compilation) 179

-Wx

(Windows applications) 111, 179

-X (disable autodependency information)

171

-y (overlays) 171

-Yo (overlays) 171

-a (align integers) 167

-AI< (Kernighan and Ritchie keywords)

174 allocate whole word for enum (-b) 168

ANSI compatible code 174 keywords (-A) 174

Borland

C++ User's Guide

violations 175 assembler code 178, 179 assembler to use (-E) 178 assume D5

=

55 (-Fs) 169

-AU (UNIX keywords) 174 autodependency information (-X) 171

-b (allocate whole word for enums)

168

-B (process inline assembler) 178

Borland C++ keywords (-Aand -AT)

174

C++ and C compilation (-P) 179

C++ inline functions (-vi) 172

-c (compile and assemble) 178

-C (nested comments) 174 code generation 167 code segment class name 177 group

177 name 178 comments, nesting (-C) 174 compilation control 178 compile and assemble (-c) 178 configuration files and

159

-D (macro definitions) 167

-d

(merge literal strings)

168 data segment class name 178 group 177, 178 name 177, 178 debugging information ( -v)

243 debugging information (-v) 171

#defines 167 ganging 167 directory (-n) 184

.DLLs with all exportables (-WD) 113, 180

.DLLs with explicit exports (-WDE) 180

DLLs with explicit exports

(-WDE) 113

-E (assembler to use) 178

-e (EXE program name) 183 emulate 80x87 (-f) 169 enable -F options (-Fm) 169 environment 183 error reporting

174

.EXE file names (-e) 183 extended 80186 instructions (-1) 167 extended and expanded memory

180

-:-f287 (inline 80x87 code) 169

Index

-f87 (inline 80x87 code)

169

-f (emulate 80x87)

169 far global variables (-Ff) 168 far objects (-zE, -zF, and -zH) 177 fast floating point (-ff) 64, 169 fast huge pointers (-h) 169

-Fc (generate COMDEFs) 168

-Ff (far global variables) 168

-Fm (enable -F options)

169 frequent errors 175

Fs (assume D5

=

55) 169 functions, void 175

-G (speed optimization) 172 generate COMDEFs (-Fc) 168 generate underscores (-u)

170

gn (stop on

warnings) 174

-h (fast huge pointers) 169 identifiers, length (-i)

174 include files 184 directory (-I) 160, 183 inline 80x87 code (-f87) 169 integer alignment (-a) 167

-jn (stop on n errors) 175 jump optimization (-0)

172

-k (standard stack frame)

170

-K (unsigned characters)

170

Kernighan and Ritchie keywords

(-AK)

174

-1

(linker options) 183

-L (object code and library directory)

160,

184 libraries 184 directory (-L)

160, 184

line numbers (-y) 171 link map

(-M)

183 linker

(-1)

183

-M (link map) 183 macro definitions (-D) 167 memory model (-rnx) 166 merge literal strings (-d) 168

-n (.OBJ and

.A5M

directory) 184·

-N (stack overflow logic)

170

nested comments (-C) 174 object code and library directory (-L)

160,

184 object files (-0) 179

.0BJs with explicit exports (-WN)

112,180

281

282 order of evaluation 164 response files and 164 overlays (-Y) 171 overlays (-Yo) 171

Pascal conventions (-p)

170

identifiers 171 pass options to assembler (-Tstring)

179

pointer conversion, suspicious 175 portability warnings 176 precedence 164 response files and 164 precedence rules

160

precompiled headers (-H) 178 process inline assembler (-B) 178 produce .A5M but don't assemble (-5) 179 project files and 59

-Q

(extended and expanded memory)

180

-rd (register variables) 173 redundant load operations (-Z) 173 register usage optimization (-Z) 173 register variables 172, 173 remove assembler options (-T-) 179

-5 (produce .A5M but don't assemble) 179 segment-naming control 177 smart callbacks (-W5) 112 smart callbacks (-W5)

180

speed optimization (-G) 172 stack overflow error message (-N)

170

standard stack frame (-k)

170

stop on

errors(-jn) 175 stop on n warnings (-gn) 174 structures and 175 symbolic debugger 171 syntax 163

-T- (remove assembler options) 179

- Tstnng (pass options to assembler) 179 toggling 159 undefine (-U) 167 underscores (-u)

170, 171

UNIX keywords (-AU) 174 using 159

-v (debugging information) 171,243

-vi (C++ inline functions) 172 virtual tables (-V and -Vn) 182 warnings

(-wxxx) 175-176

warnings

(-wxxx) 175

-WDE (DLLs with explicit exports) 113

Windows applications (-W)

108,

111, 114

Windows applications (-W) 179

-y (line numbers) 171

-Z (register usage optimization) 173

-zX (code and data segments) 177, 178 protected mode 158 real mode 158 response files 163 option precedence 164 syntax 158

TLINK and

240

Turbo Assembler and 163 using 159

Windows and

107, 159

commands See also command-line compiler, options; individual command names choosing with a mouse 9 with keyboard 9 editor 146-152 block operations 147, 148-149 cursor movement 146, 148 insert and delete 147 printing

MAKE option 216 comments delimiters 153 pair matching 154, 155 in makefiles

201

nested 69, 174 communal variables 168 compatibility initialization modules 237 compilation 166, See also compilers command-line compiler options 178 rules govern~ng

163 speeding up 4, 62, 159 to .EXE file 45, 46 to .OBJ file 45

Windows applications

108

Compile menu 45

Compile to OBJ command 45 hot key 12

Compiler command 61

Borland

C++

User's Guide

Compiler Messages dialog box

compilers See also compilation

C++ 67 code optimization 68 command line See command-line compiler configuration files See configuration files memory models See memory models optimizations for speed or size 69 speeding up 4, 159 stopping after errors and warnings

Turbo editor macro 77 compiling See also compilers conditional breakpoints See breakpoints, condi tional conditional execution directives (MAKE) 218 expressions in

219

$CONFIG transfer macro 77 configuration files 77 command-line compiler

160, 164

creating 164 overriding 159, 164 priority rules 164

IDE

20-23

projects and

TCCONFIG.TC 21 saving 95 constants debugging

hexadecimal too large 175 manifest See macros octal too large 175 symbolic See macros

Contents command

100

hot key 12 control characters entering in IDE 18 format specifier 53 conventions, typographic 2 conversions floating point

ANSI rules 169 pointers suspicious 175 specifications See format specifiers

Index

coprocessors See numeric coprocessors

Copy command 35, 149 hot key 11

Copy Example command 36, 99 copying, and pasting

See editing, copy and paste copyright information 27

CPP (preprocessor) See The online document

UTIL.DOC

.CPP files See C++

CPU registers 98

Create Backup Files option 92 creating new files See files, new

Ctrl-Break 41

Current window option 91 cursor

See also editor, cursor movement

Cursor Through Tabs option 93 customizing See also BCINST

IDE

Cut command 35, 149 hot key 11

CWINx.LIB 238

Cx.LIB238 o

-D BCC option (macro definitions) 167

-d

BCC option (merge literal strings) 168

/d IDE option (dual monitors) 6

$d MAKE macro (defined test) 213 expressions and

220

-D MAKE option (define identifier) 197, 211

-d RC option (define symbol) 122

/d TLINK option (duplicate symbols) 242 data aligning 61 static, DLLs and 127 data members See C++, data members data segment group 177, 178 names 73 naming and renaming 177, 178 removing virtual tables from 68, 182

-WD option and 113,

180

data structures

See also arrays; structures data types char default 62

283

changing

170

converting

See conversion floating point See floating point integers

See integers

Debug Info in OBJs option 64

Trace into command and 43

Debug menu 46 debugger, integrated See integrated debugger

Debugger command 87

Debugger Options dialog box 87 debugging

See also integrated debugger arrays 49 breakpoints See breakpoints call stack 51 classes 49,

constants

Debug Info in OBJs 64 dialog box choices 87 display swapping 88 dual monitors and 88 excluding information 59 expressions

format specifiers 51 functions 49 heap size 89 hot keys 12 information 41, 87,243 command-line compiler option 171 in .EXE or OBJ files 171 storing 64 inspecting values 47 line numbers information 63

MAKE 197 map files 244 pointers 48 stack overflow 67 starting a session 41

Step Over command 43 structures and unions 49 subroutines 66

TLINK and 248

Trace Into command 42 types

variables

watch expressions See watch expressions

Windows applications 46

.DEF files import libraries and 83

$DEF transfer macro 78 default assembler 178 default buttons 17

Default Extension option 94

Default Libraries option 84

#define directive command-line compiler options

167 ganging 167 defined test macro (MAKE) 213

Defines option 62 transfer macro 78

Delete Item command 58

Delete Item command 133

Delete Watch command 54 deleting text redoing 35 undoing 34,

150

delimiters directional 153 nesting 154 nondirectional 153 unmatched 155

$DEP transfer macro 78 dependencies 83 automatic See autodependencies checking

MAKE (program manager) 208 explicit 78 autodependencies and 78 desktop clearing 27 saving options in 94 desktop files (.DSK) default 22 projects and 22

Desktop option 91

Desktop Preferences dialog box 94 dialog boxes See also buttons; check boxes; list boxes; radio buttons arrows in 17 defined 17 entering text 18

$DIR transfer macro 78 directional delimiters See delimiters

284

Borland C++ User's Guide

directional pair matching 153 directives

200

MAKE See MAKE (program manager), directives

Directories command 89 dialog box 89 directories

.ASM and

.OBI

command-line option 184 changing

defining 89 include files

160,

183, 184 example 186

MAKE

197 transfer macro 79 libraries 185 command-line option

160, 184

example 186 transfer macro 79 output

project files 22 projects 135 semicolons in paths

transfer macro 78 disk caches extended and expanded memory and 181 disk space running out of 273 display formats debugger 51 repainting 27 swapping 88 dual monitors and 88

Display Warnings option 71

DLLs See also import libraries building

103-129

C++ and classes 127 mangled names 129 classes and 191 compiler options and 128 compiling and linking 123 creating 66, 79, 113, 125,

180

defined 123 exit point 125

Index

export functions hiding 191 extended and expanded memory and 122

IMPLIBand multiple 193 import libraries and 83,

190, 192

initialization functions 125

LibMain function and 125 libraries 117, 118 linker and 83 linking

Resource Compiler and 118

MAKE and 83,238 mangled names and 191 memory models 118 memory models and 115 packing code segments 85,247 pointers and 126 private 122 setting 84 smart callbacks and 113 startup files 118 static data 127

TLINK option 248 virtual tables and 128

WEP function 125

DOS commands

MAKE and

205

running from the IDE 82 environment strings macros and 213

MODE command 6 output viewing from IDE 97 paths

MAKE 216 shelling to

TSRsand 32 wildcards 28

DOS Overlay command 65

DOS Shell command 8, 32

DOS Standard command 65 dot directives (MAKE) 216 double-click speed (mouse) 94

$DRIVE transfer macro 79

DS register (data segment pointer) 62

285

.DSK files default 22 projects and 22 dual monitor mode 6 dual monitors 6 display swapping and 88

DOS command line and 33 duplicate, strings, merging 62

Duplicate Strings Merged option 62 duplicate symbols 85

.LIB and .OB} files and 243

TLINK and 242 dynamic link libraries See DLLs

-E BCe option (assembler to use) 178

-e

BCC option (EXE program name) 183

Ie

IDE option (expanded memory) 7

-e RC option (EMS) 122

IE

TLffi option (extended dictionary) 226,229

Ie

TLINK option 243

Edit command (Turbo C 2.0) 145 menu 33 windows loading files into 137

Edit Watch command 54

Edit windows activating 145 cursor moving 146, 148 option settings 92 editing 19, See also editor; text autoindent mode

150

block operations 147, 148-149 deleting text 93, 149 hiding

unhiding 149 marking 93 printing 149 reading and writing 149 selecting blocks 33,93, 149 breakpoints 55

Clipboard text 36 commands 146-152 cursor movement 146, 148 insert and delete 147 copy and paste 149,

See also Clipboard

286 hot key 11 cut and paste 34, 35, 149 entering text 146 hot keys 11, 146-152 insert mode overwrite mode vs. 92 matching pairs See pair matching miscellaneous commands

150

options setting 92 pair matching See pair matching pasting See editing, copy and paste place marker

150

print file 149 quitting

150

redoing undone text edits 35 search and replace 151-152 options 151 selecting text 33 setting defaults 92 tab mode toggle

150

tabs

150

undelete 34,

150

undoing text edits 34,

150

watchpoints 54 editor

See also editing features 19 macro language (TEML) using 77 macros See also MAKE (program manager), macros options setting 92 redoing undone text edits 35 setting defaults 92 tabs in 92 undoing text edits 34,

150

Editor Files option 91

Editor Options 92

$EDNAME transfer macro 79

E~A

See

Graphics Adapter

!ehf MAKE dIrective 218 defined test macro and 213 macros and 213 ellipsis ( ... ) 9, 17

!else MAKE directive 218

EMS See extended and expanded memory

Borland

C++

User's Guide

EMU.LIB 238, 239 emulation

80x87169 emulation, 80x87 floating point 63

!endif MAKE directive 218

Enhanced Graphics Adapter (EGA) 91 palette

IDE option 7

Entry /Exit Code command 65 dialog box 65 enumerations (enum) assigning integers to 175 treating as integers 61, 168

Environment command 90 environment

DOS See also integrated environment environment, DOS macros and 213

Environment option

Auto Save 91

Environment Options dialog box 147,

150

$ERRCOL transfer macro 79

$ERRUNE transfer macro 79

$ERRNAME transfer macro 79 terror MAKE directive 220 errors See also warnings

ANSI 175

Frequent 73 frequent 175

MAKE (list) 222-224 messages compile time 135, 136 removing 137 saving 137 searching 40 setting

next hot key 12, 137 previous hot key 12, 137 reporting command-line compiler options 174 stopping on

Index

syntax project files 135, 136

TLINK (list) 258 tracking project files 135, 136

Esc shortcut 17

Evaluate command format specifiers and 51

Evaluate/Modify command

hot key 12 evaluation order command-line compiler options 164 in response files 164 examples copying from Help 36, 99 library and include directories 186

MAKE (program manager) 197 batch files 204

.EXE files

.COM files and 249 crea ting 12, 45, 46 debugging information 248 directory 90 file name transfer macro 79 linking 46 making

naming 45

$RC transfer macro and

renaming 122

.RES files and 81

TLINK and 248 user-selected name for 183 executable files See .EXE files

$EXENAME transfer macro 79 exit codes

MAKE and 202 exit procedure, Windows 125 exiting Borland C++ 8 expanded memory See extended and expanded memory explicit library files 183 rules (MAKE) 200, 206

_export (keyword)

Windows applications and 66, 112, 113,

180

exports case sensitive 85

287

expressions See also debugging, watch expressions debugging

evaluating restrictions on 51

MAKE and 219,

220

nested pair matching 152 values displaying 51

$EXT transfer macro 79 extended 80186 instructions 167 extended and expanded memory controlling use of

180

disk caches and RAM disks and 181

DLLs and 122

IDE options 7

RAM disk and 8

Resource Compiler and 122

TLINK and 249 extended dictionary

TLIB and 226, 229 extension keywords

ANSI and 174 extensions, file, supplied by TLINK 234

External option

C++ Virtual Tables command-line option 182

C++ Virtual tables 67 extract and remove (TLIB action) 228

-f287 option (inline 80x87 code) 169

-f87 option (inline 80x87 code) 169

-f BeC option (emulate 80x87) 169

-f MAKE option (MAKE file name) 195, 197 far variables 168

Far Data Threshold type-in box 64 far objects See objects, far

Far option

C++ Virtual tables 68

Fast Floating Point option 64 fast huge pointers 169

Fast Huge Pointers option 64 fatal errors See errors

-Fc BCC option (generate COMDEFs) 168

288

-fe RC option (rename .EXE file) 122 features editor 19

IDE 3

-Ff BCC option (far global variables) 168

-ff option (fast floating point) 64, 169 file-inclusion directive (!include) 217

File menu 27 file-name macros (MAKE) 215 files See also individual file-name extensions assembly language

See assembly language backup (.BAK) 92 batch

See batch files

C++

SeeC++

closed reopening 98

.COM 237, 247

.EXE files and 249

TUNK and 248 compiling as C++ or C 179 configuration See configuration files

.CPP See C++ desktop (.DSK) default 22 projects and 22 editing

See editing executable See .EXE files extensions 79, 234 include

See include files information in dependency checks 138 information on 31 library See libraries, files loading into editor 137 make See MAKE (program manager) map See map files multiple

See projects names extensions (meanings) 234 macros transfer 76 new 29,

150

NONAME29 open choosing from List window 98 opening 28,

150

hot key

out of date, recompiled 138

Borland

C++

User's Guide

path macros 78 printing 31 project (.PRJ) response

See

projects

See

response files saving 29,

150

all

30,

81 automatically 91 hot key

with new name or path

source

.ASM command-line compiler and 157 startup

DLLsand 118

.TC

See

configuration files, integrated environment

.TDS 64 updating 194 filling lines with tabs and spaces 92 filters 77

GREP 77

Resource Compiler 77

TASM 77

Find command 37, 151,

See also

searching

Find dialog box 37, 151 settings saving 95 floating point

See also

integers; numbers; numeric coprocessors

ANSI conversion rules 169 code generation 63 fast 64, 169 format specifier 53 inline 80x87 operations 169 libraries 169

TUNKand238 math coprocessor and 169

-Fm BCC option (enable -F options) 169

-fo RC option (rename .RES file) 122 format specifiers debugging and 51 table 53

43/50-line display 91 forward forward searching 38 pair matching 153

Index

FP87.LIB 239

Frequent Errors warnings 73 frequent errors 73, 175

Frequent Errors dialog box 73

-Fs BCC option (assume DS = SS) 169 full file name macro (MAKE) 214 full link map 183 functions

See also

scope

C-type

170

call stack and 51 calling conventions 66 export

Windows applications and 65, 111, 112,

180

exporting 113,

180

help

100

inline

C++ precompiled headers and 272 inspecting 49 locating

parameters

See

arguments searching for

stepping over 43 tracing into 42 void returning a value 175

Windows 113,

180

-G BCC option (speed optimization) 172 ganging command-line compiler options

#define 167 macro definition 167 defined 167, 184

IDE 185 library and include files 184

Generate COMDEFs option 64

Generate Underbars option 63

Get Info command 31 dialog box 32 global menus

See

menus global variables word-aligning 167

289

-gn BCCoption (stop on n warnings) 174

Go Cursor command 42

Go to Cursor command hot key

10, 12

Go to Line Number command 39 dialog box

graphics library

TLINK and 238

Graphics Library option 84

GREP

See

The online document UTIL.DOC

GREP (file searcher) capturing messages 77 wildcards in Borland C++ 37

GREP2MSG.EXE 77 group names 73

Group Undo option 93

Undo and Redo commands and 35

H

-h BCC option (fast huge pointers) 169

-H BCe option (precompiled headers) 178

IDE option (list options)

-h

MAKE option (help) 197

-h RC option (help on options) 122 hdrfile pragma 272, 273 hdrstop pragma 272, 274 header files

See also

include files help

100

precompiled

See also

precompiled headers searching for 185 variables and 64 heap size 89

Help button 17 menu 98 windows closing 99 copying from 36, 99 keywords in 99 opening 99 selecting text in 99 help accessing 98

CandC++

100

290 help on help

101

hot keys

10, 12

IDE 7 index

100

keywords 99 language

100

MAKE 197 previous topic

100

status line

16 table of contents

100

Help on Help command

101

hexadecimal numbers hexadecimal

See

numbers, history lists 19 closing 27 saving across sessions 94 wildcards and 28 hot keys debugging 12 editing 11 editor 145, 146-152 help

10, 12

make project 136 menus

10, 11

next error 137 previous error 137 transfer macros 75 transfer program names 75 using

huge pointers 169 hyphen (-) MAKE command (ignore exit status)

202

-i BCC option (identifier length) 174

-I BeC option (include files directory)

160, 183

-i MAKE option (ignore exit status) 197

-I MAKE option (include files directory) 196,

197

-i RC option (include files) 122

Ii

TLINK option (uninitialized trailing segments) 243

IDE

See

integrated environment identifiers

Borland C++ keywords as

70, 174

defining 211 duplicate 85

Borland

C++

User's Guide

length

Pascal-type 171 significant length of 167, 174 undefining 167 underscore for

170

!if MAKE directive 218 defined test macro and 213 macros and 213 ignore exit status (MAKE command)

202

.ignore MAKE directive 216

IMPDEF (module definition files)

190-192

IMPLIB and

190

IMPL2MSG.EXE 77

IMPLIB (import libraries)

192-193

DLLSand 193

IMPDEF and

190

warnings 193

$IMPLIB See also import libraries

$IMPLIB transfer macro 79

IMPUB program See import libraries implicit library files 183 rule (MAKE)

200

import libraries 192-193, See also DLLs creating new

193 customizing

190

DLLSand

190

DLLs and 83, 192 generating 83

IMPLIB program executing 79 module definition files and 124 transfer macro 79

$INC transfer macro 79

#include directive See also include files angled brackets and 185 directories 89 quotes and 185

!include directive (MAKE) 196,217

Include Directories input box 89

Include Files command

include files See also header files automatic dependency checking (MAKE)

208

command-line compiler options 184 directories

160,

183, 184 multiple 186 transfer macro 79 help

100

MAKE 196,217 directories 197 projects 133

Resource Compiler and 122 searching for 185 user-specified

160, 183

Include Files command 133

Include Files dialog box

incremental search 19 indenting automatically 92

Index command hot key 12

Index command (help)

100

indexes See arrays initialization modules compatibility 237 used with TLINK 237 initialization modules, used with TLINK 236 initialized data segment See data segment inline assembly code 178 inline code See assembly language, inline routines; 80x87 math coprocessor input boxes 18

Insert Mode option 92

Inspect command 47

Inspect command hot key 12

Inspector windows 47 arrays 49 class

classes 49 constant

function 49 ordinal 48 pointers 48 structures and unions 49

Type

Instruction Set radio buttons 63 integers See also floating point; numbers aligned on word boundary 167 assigning to enumeration 175

Index

291

integrated debugger

See also

debugging breakpoints

See

breakpoints debugging information for 171 integrated environment 3 command-line arguments and 44 command-line options 5 build

(lb) 5

dual monitors (ld) 6

EGA palette (lp)

7 expanded memory (Ie)

extended memory (I x) 7 help (lh) 7 laptops (11) 7 listing (lh) 7 make (1m) 7

/ P EGA palette 7

RAM disk (lr) 8 syntax 5

/x extended memory 7 co~guration files

See

configuration files, mtegrated environment control characters and 18 customizing

debugging

See

debugging

DLLsand 123

DOS commands and 82 editing

See

editing features 3 ganging

185 makes 137 memory needs 82 menus

See

menus module definition files and 116 multiple library directories 185 protected mode 4

Windows and 5 real mode 4 settings saving 95 starting up 4

Windows and 5,

107

linking 116

-jn BCC option (stop on n errors) 175

Jump Optimization option 68

292 jump optimization 172

-k BCC option (standard stack frame)

170

-K BCC option (unsigned characters)

170

-K MAKE option (keep temporary files) 197

203 '

-k RC option (disable load optimization) 122

K&R

See

Kernighan and Ritchie

Keep Messages command . toggle 137

Kernighan and Ritchie keywords

70,

174 keyboard choosing buttons with 17 choosing commands with 9 selecting text with 33 keys, hot

See

hot keys keywords

ANSI command 174

Borland C++

using, as identifiers 174 help

100

Help windows 99

Kernighan and Ritchie using 174 options

UNIX using 174

-1 BCC option (linker options) 183

-L BeC option (object code and library directory)

160, 184

/1 IDE option (LCD screen) 7

-I RC option (expanded memory) 122

/1 TLINK option (line numbers) 243 language help

100

laptops

IDE option (/1) 7 left-handed mouse support for 94

.LIB files

See

libraries

Borland

c++

User's Guide

$LIB transfer macro 79

LibMain (function)

125 return values 125 libname (TLIB option) 226 librarian

See

TLIB libraries command-line compiler options 184 default

84 directories

90, 184

command-line option

160, 184

multiple 186 transfer macro 79

DLLs and 117, 118 duplicate symbols in

243 dynamic link (DLL)

See

DLLs explicit and implicit

183 files

90, 160, 184

floating point 169

TLINK and 238 graphics

TLINK and 238 import

See

import libraries linking 46 math project library overrides and 141 memory models

240

memory models and

238-240

numeric coprocessor

239 object files 225 creating

228 order of use 238 overiding in projects

141 page size 229 rebuilding 171 routines

BOxB7

floating-point emulation 169 run time

TLINK and 239 searching for 185

TLINK and 236, 238 ignoring 246 user-specified 183 utility

See

TLIB

Windows applications and

238

Library Directories input box

Index

library files

See

libraries

-lim32 RC option (expanded memory)

$LINE transfer macro 79

122 line numbers

See

lines, numbering

Line Numbers Debug Info option 63 lines filling with tabs and spaces 92 moving cursor to

39 numbering 13, 79 in object files 171 information for debugging 63

TLINK and 243 restoring (in editor) 34, 35,

150

Link

EXE

File command

46 link map, full 183

Linker command 84 dialog box 84

Windows and

116 linker

See also

TLINK case sensitive linking 85 command-line compiler options

183

DLLsand 83 link map creating 183 options from command-line compiler 183 speeding up 4 linking excluding from

59 list boxes 19 file names

29 searching incrementally

100

List command hot key 12

List window 95, 98 listfile (TLIB option) 226 literal strings

See

strings, literal

Load a File dialog box 28,

150

load operations redundant, suppressing 173 load optimization disabling (Resource Compiler) 122 local menus

Local option

See

menus

C++ Virtual tables

293

Local Options

C++ Virtual Tables command-line option 182 command 59, 133

Locate Function command

dialog box

. LST files

See files; listfile (TLIB option)

-M BCC option (link map) 183

ImIDE

option (make) 7

-m RC option (expanded memory) 122 macros

See also editor, macros; MAKE

(program manager), macros command-line compiler 167

DOS environment strings and 213 path

(MAKE)

216 editor 77 ganging 167 invocation defined 212

MAKE

See MAKE (program manager), macros preprocessor 62 transfer

See

transfer macros

Turbo editor

See

The online document

UTIL.DOC

MAKE macro 213

MAKE

(p;ogrammanager) 193-224 automatic dependency checking 197,

208

batching files and

203

BUIL TINS.MAK file 196 clocks and 194 commands

(hide commands)

202

hiding (@)

202

hyphen (-) (ignore exit status)

202

-num

(stop on exit status

num)

202

debugging 197 directives

.noautodepend 216

.autodepend 216 command-line compiler options and 216 conditional execution 218

294 expressions in 219 defined 215 dot 216

!elif 218 macros and 213

!else 218

!endif 218 terror

220

file inclusion 217 lif 218 macros and 213

.ignore 216

!include 217

.noignore 216

.nosilent 216

.noswap 216

.silent 216

.swap 216

!undef 221

DLLs and 83, 238

DOS commands and

205

errors (list) 222-224 example 197 exit codes and

202

explicit rules

See MAKE (program manager), rules functionality 194 hide commands

202

implicit rules See MAKE (program manager), rules

!include directive 196 integrated environment makes and 137 macros 209, 211, 213 base file name ($*) 214 defined test 213

!elif directive and 213 example

209

file name and extension ($.) 215 file name only ($&) 215 file name path ($:) 215 full file name ($<) 214 lif directive and 213 in expressions $d

220

__ MAKE __

213 predefined 213 undefining 221 version number 213

Borland

C++ User's Guide

makefiles comments in

201

creating

200

defined 198 naming

200

parts of

200

Windows applications and

109

operators

220

options 196

-? (help) 197 automatic dependency checking (-a)

208

build all

(-B)

197 default (-w) 197 define identifier (-D) 197 conditional execution 218 don't print commands (-s) 197 file name (-f) 195, 197 help (-? and -h) 197 ignore exit status (-i) 197 include files directory (-I) 196, 197 keep files (-K) 197,

203

-n (print commands but don't execute) 197 saving (-w) 197 swap MAKE out of memory (-5) 197 undefine

(-U)

197 using 195

-W (save options) 197

.path directive 216 printing commands 216 redirection operators

202

rules explicit considerations

207

defined

206

example

201,207

implicit 199 discussion

208

example

201

implicit rules explicit rules and

208

stopping makes 83, 136 swapping in memory 216 syntax 195 wildcards and

206

Windows applications and

109, 238

Make command 82

Make EXE File command 45 hot key

10, 12

makefiles makes

See

MAKE (program manager)

IDE option 7 mangled names

DLLsand 191 manifest constants map files 183 debugging 244 directory

See

macros generated by TLINK 244 options 84

Match Pair command 152-156 math coprocessors

See

numeric coprocessors

MATHx.LIB 238 maximize

See

Zoom command

$MEM transfer macro 79, 82 memory dump format specifier 53 extended and expanded expanded memory controlling

180

IDE and

RAM disk and

8 heap size 89 requirements

See

extended and

IDE 82 swapping MAKE in 216 transfer programs 79, 82 memory models automatic far data and 64 changing 61 command-line options 62, 166 compatibility libraries for 237

DLLs 118 initialization modules 237 libraries

240, 238-240

smart callbacks and 66, 112,

180

startup modules

240

tiny library

240

TLINK and 236, 238

Windows applications and 115 menu bar menus

See

menus

See also

individual menu names accessing 8

Index

295

Break Make On 136 commands

See

individual command names hot keys

10, 11

opening 9, 145 reference 25 with an ellipsis ( ... ) 9, 17 with arrows (~) 9

Message Tracking toggle 136

Message window 96, 137 capturing output into 77 copying text from 35, 81 removing messages 46 messages

See also

errors; warnings appending 91 capturing from programs 77 column number 79 filename 79 line number 79 removing 46

TLINK (list) 258

Messages command

Microsoft Windows

See also

Microsoft Windows applications command-line compiler and 159

_export and 114 libraries 117 modes

IDE and 5 modules compiling and linking

103

object files 117 options standard mode (/s) 159 prolog and epilog code 111 resources

See

resources running Borland C++ with 5

Microsoft Windows All Functions Exportable command 65

Microsoft Windows applications

103-129, See also

Microsoft Windows code segments 85,247 command-line compiler and

107

command-line compiler options

108, 111,

112, 113, 179,

180

debugging 46

_export and 113 export functions and 65, 111, 112,

180

IDE and

107

IDE options 65 import libraries

190

linking 116

MAKE and 238 memory models and 115 modes 122 optimizing for 69 overlays and 246 prolog and epilog code 65, 111

Resource Compiler and

103, 105, 118

setting application type 84 setting options for 65, 86 smart callbacks and 66, 112,

180

TLINK and

240

TLINK option 248

WHELLO

104

WinMain function and

120

Microsoft Windows DLL All Functions

Exportable command 66

Microsoft Windows DLL Explicit Functions

Exported command 66

Microsoft Windows Explicit Functions

Exported command 66

Microsoft Windows Smart Callbacks command

MODE command (DOS) 6 models, memory

See

memory models module definition file case sensitivity and 242 module definition files

105

defined 124 exported functions and 66

EXPORTS section case-sensitive 85

IDE options and 116

IMPDEF and

190

import libraries and 124

IMPORTS section case-sensitive 85

LibMain function and 125

TLINK and 116

/Tw TLINK option and 116, 248 module names, TLIB 227 monitors

See

screens dual 6, 33, 88

296

Borland

C++ User's Guide

number of lines 91

More ANSI Violations dialog box 72

More Frequent Errors dialog box 73 mouse buttons switching 94 choosing commands with 9, 17 double-click speed 94 left-handed support for 94 options 94 reversing buttons 94 right button action 94 selecting text with 34 support for 3

Mouse Double Click option 94

Mouse Options dialog box 94 moving text

See editing, block operations multi-source programs See projects

-multinst RC option (expanded memory) 122 multiple files See projects multiple listings command-line compiler options

#define 167 include and library 184 macro definition 167

-rnx options (memory models) 166

-n BCC option (.OBJ and .ASM directory) 184

-N BCC option (stack overflow logic)

170

-n MAKE option (print commands but don't execute) 197

In

TLINK option (ignore default libraries) 246

$NAME transfer macro 80

Names command 73 names See identifiers mangled

DLLsand 129 nested comments 174 delimiters See delimiters

Nested Comments option 69, 155

New command 29,

150

New Value field 51

New Window option 91

Index

Next command 96 hot key

10, 12

Next Error command

hot key 12

.noautodepend MAKE directive 216

.noignore MAKE directive 216

NONAME file name 29 nondirectional delimiters

See delimiters nondirectional pair matching 153 nonfatal errors See errors

.nosilent MAKE directive 216

.noswap MAKE directive 216

$NOSW AP transfer macro 80 null character See characters, null

-num

MAKE command

202

numbers See also floating point; integers column 77 decimal 89 format specifier 53 hexadecimal 89 constants too large 175 format specifier 53 line 79 octal constants too large 175 real See floating point numeric coprocessors See also floating point emulating 169 generating c~de for 169 inline instructions 63, 169 libraries

TLINK and 239 o

-0 BCC option Gump optimization) 172

-0

BCC option (object files) 179

10

TLINK option (overlays) 246

ITw

option and 246

.OBJ files compiling 179 creating 45 debugging information 64 dependencies 83 directories

90, 184

DLLsand 117

297

duplicate symbols in 243 libraries advantages of using 225 creating 228

TUB and 225 line numbers in 171

Windows and 117 object files See .OBJ files object-oriented programming See c++ objects See also C++ far class names 177 generating 64 group names 177 segment names 177

OBJXREF See The online document UTIL.DOC octal numbers See numbers, octal

OKbutton 17 online help

See help

OOP

SeeC++

Open command 28,

150

hot key

10, 11

Open Project command 57 operations (TLIB option) 226 operators

MAKE

202, 220

precedence See precedence

Optimal Fill option 92

Optimizations command 68 dialog box 68 optimizations 68 command-line compiler options 172 fast floating point 64 for speed or size 69 precompiled headers 274 register usage 173 registers usage 172

Resource Compiler 122

Windows applications and 69 options

See specific entries (such as commandline compiler, options)

Options menu 60 settings saving 95

298 ordinals, inspecting 48

Out-Line Inline Functions option 68

$OUTNAME transfer macro 80 output capturing 77 to DOS viewing from IDE 97

User Screen 97

Output command 97

Output Directory input box 90

Output window copying text from 35 overlays generating 171 projects and 59 supporting 65

TLINK and 246

Windows applications and 246

Override Options dialog box 59

Overwrite Mode 92 p

-P BCC option (C++ and C compilation) 179

-p BCC option (Pascal conventions)

170

Ip

IDE option (EGA palette) 7

-p RC option (private DLLs) 122

IP

TLIB option (page size) 229

Pack Code SegJ;ll.ents option 85 page size (libraries) 229 pair matching 152-156 angle brackets 152 backward 153 braces 152 brackets 152 commands 152 comment delimiters 152, 154, 155 directional 153 double quotes 152 examples 155 forward 153 nested expressions 152 nondirectional 153 parentheses 152 rules 153 single quotes 152 parameter-passing sequence, Pascal

170

Borland C++ User's Guide

parameters

See

arguments

Pascal calling convention 66 identifiers of type 171 parameter-passing sequence

170

Paste command 35, 149 hot key 11 pasting

See

edit, copy and paste path transfer macro

path names in Directories dialog box

.path directive (MAKE) 216

Persistent Blocks option 93

PF87.LIB 238 place markers (editor)

150

pointers

DLLs and 118, 126 fast huge 64, 169 format specifier 53 inspecting values 48 memory regions 53 suspicious conversion 175 virtual table

32-bit 68, 182

-WD option and 128,

180

polymorphism See C++ pop-up menus 9, See also menus

Portability dialog box 71 portability warnings 71, 176

#pragma hdrfile 272, 273

#pragma hdrstop 272, 274 precedence command-line compiler options

160, 164

response files and 164

TLIB commands 227 precompiled headers 271-275 command-line options 178 controlling 272 drawbacks 272 how they work 271 inline member functions and 272 optimizing use of 274 rules for 273 using

IDE 62

Preferences dialog box 91

Index

Previous Error command

hot key 12

Previous Topic command

100

hot key 12

Print Block command 149

Print command 31

Print File command 149

PRJ2MAK See The online document UTIL.DOC

.PRJ files See projects

PRJCFG

See The online document UTIL.DOC

PRJCNVT

See

The online document UTIL.DOC

$PRJNAME transfer macro

procedures See functions program manager (MAKE) See MAKE

(program manager)

Program Reset command 42 hot key 12 programs

C++ See C++ capturing output 77 ending 41 filename 79 heap size 89 memory assignments 82 multi-source See projects rebuilding 41, 46 resetting 42 running 41 arguments for 44 to cursor 42

Trace Into 42 transfer list

140

transferring to external from Borland C++ 74

Project command 98 menu 57

Project File dialog box 57

Project Manager 41, 131-144, See also projects closing projects 58

DLLs and 118

Include files and

Resource Compiler and 119 resources and 119

Windows applications and 118

299

Project Name command 76

Project Notes command 98

Project Notes window 144

Project option 91 projects 131-144, See also Project Manager autodependency checking 83 speeding up 83 automatic dependency checking and 138 building 131 changing 22 closing 58 default 22 desktop files and 22,

20-23

directories 135 directory 22 error tracking 135, 136 excluding from 59

.EXE filenames and 45 files adding 133 command-line options and 59 converting 57 deleting 133, 134 file name transfer macro

include 133 information 139 list 133 options 133 out of date 138

Turbo C 2.0 57 viewing 143

IDE configuration files and

include files 133 information in 131 libraries and overriding 141 math libraries and 141 loading 21 makes and 137 making hot key for 136 managing 98 meaning of 58 naming 132 new 133 notes 98, 144

300 overlays and 59 saving 134 translator option 59 translators See also Transfer default 139 example

140

multiple 138 specifying 139 prolog and epilog code generating 65, 111

$PROMPT transfer macro

protected mode command-line compiler and 158

IDE 4

Windows and 5 pseudovariables, register using as identifiers 174

PUBDEFs

COMDEFs versus 64

Public option c++ Virtual Tables command-line option

182

C++ Virtual tables 67 pull-down menus See menus

Q

-Q

BCC options (extended and expanded memory)

180

QEMM7

Quit command 8, 33,

150

-r BCC option (register variables) 172

-r RC option (compile .RC to .RES) 122

frx

IDE option (RAM disk) 8 radio buttons 18

RAM disk

IDE and 8

RAM disks extended and expanded memory and 181

RC2MSG.EXE 77

.RC files

See also Resource Compiler compiling into a .RES file 81

$RC transfer macro and

80, 81

$RC transfer macro

Bor/and

C++

User's Guide

-rd option (register variables) 173 real mode command-line compiler and 158

IDE 4 real numbers

See

floating point rebuilding libraries 171 redirecting program output 77 redirection operators

MAKE

202

Redo command 35

Group Undo and 35, 93 register (keyword)

DS (data segment pointer) 62 pseudovariables using as identifiers 174 reusing 68

SS (stack segment pointer) 62 variables 173 suppressed 172 toggle 172 windows 98 remove (TLIB action) 228

Remove All Watches command 55

Remove Messages command 46, 137

Repaint Desktop command 27

Replace command 38, 152 dialog box 39, 152 replace (TLIB action) 228

Replace dialog box settings saving 95

.RES files

See also

resources binding to an .EXE file 81

$RC transfer macro and

resetting programs 42 resident utilities extended and expanded memory and 181 resize corner 14 resize corners 15

Resource Compiler

120, See also

.RC files behavior changing

capturing messages 77

.EXE files renaming 122 funcitonality

105

include files 122 invoking

108

linking and 118 messages 122 options 122 help 122

Project Manager and 119 resources files renaming 122 syntax 121 transfer macro

Windows and

103

Windows applications and

105

resources

See also

.RES files adding

108, 118

compiling

120

defined

105

files renaming 122

Porject Manager and 119 rebuilding automatically 78 response files defined 163, 235 option precedence 164

TLIB228

TLINK and 235 restrictions, TLINK 249

Result field 51

Reverse Mouse Buttons option 94

Right Mouse Button option 94

Ritchie, Dennis

See

Kernighan and Ritchie

Run command 41 menu 41

Run command hot key 12 running programs 41

Index

301

-s

BCC option (produce .ASM but don't assemble) 179

-s MAKE option (don't print commands) 197

-S MAKE option (swap MAKE out of memory)

197

/s Windows option (standard mode) 159 sample programs copying from Help window 36

$SA VB ALL transfer macro 81

Save All command

Save As command

$SA VB CUR transfer macro 81·

Save command 29, 95,

150

hot key

10, 11

Save File As dialog box

Save Old Messages option 91

$SA VB PROMPT transfer macro 81

Screen Size option 91 screens

LCD

IDE option 7 number of lines 91 repainting 27 two using 6 scroll bars 14, 15 scrolling windows 15

Search Again command 39, 151 hot key 11 search and replace 151-152,

See also

searching

Search menu 36, 151-152 searching and replacing text 151, 151-152 direction 38 error and warning messages

functions

in list boxes

100

include files 185 libraries 185 origin 38 regular expressions 37 repeating 39 and replacing text 38 scope of 38 search and replace 38 searching and replacing text 151-152

Segment Alignment option 85

Segment Names dialog box 74 segment-naming control command-line compiler options 177 segments aligning 85 code discardable 246 minimizing 85, 247 packing 85, 247 controlling 177 initializing 84 map of

ACBP field and 245

TLINK and 244 names 73 uninitialized

TLINK and 243 semicolons (;) in directory path names

Set Application Options dialog box 86 shortcuts

See

hot keys

Show Clipboard command 36

.silent MAKE directive 216 simulated EMS 7

Size/Move command 95 smart callbacks

DLLs and 113 memory models and 112,

180

Windows applications and 112,

180

Smart option

C++ Virtual Tables command-line option 182 c++ Virtual tables 67 software

See

programs

Source command 69, 155

Source Debugging command 41 and Trace Into command 43 source files

.ASM command-line compiler and 157 multiple

See

projects separately compiled 225 source-level debugger

See

Turbo Debugger

Source Options dialog box 69, 155

302

Borland

C++

User's Guide

Source Tracking option 91

Source Tracking options 137 spaces vs. tabs 92 speed optimization 172 spreadsheets See Turbo Calc

SS register (stack segment pointer) 62 stack

Call Stack command 51 overflow 67,

170

standard frame generating

170

warnings 85 standalone debugging information 87 standalone utilities 189, See also MAKE

(program manager); TLIB (librarian); TLINK

(linker); TOUCH standard library files

See libraries standard stack frame generating

170

Standard Stack Frame command 66

Standard Stack Frame option 52 start-up and exit command-line compiler 158

IDE 4 startup code (TLINK) 237 startup files

DLLs and 118 startup modules for memory models

240

static data

DLLsand 127 status line 16

Step Over command 43 hot key

10, 12

strings duplicate merging 62 format specifier 53 literal merging 168 structures

ANSI violations 175 format specifier 53 inspecting 49 undefined 175 zero length 175 suppressing load operations 173

Index

.swap MAKE directive 216 swapping displays 88 to User Screen 80 switches

See command-line compiler, options; integrated environment, options

.SYM files 271, 272 default names 272 disk space and 273 smaller than expected 273 symbolic constants

See

macros debugger See Turbo Debugger symbols action

See

TLIB duplicate 85 warning (TLINK) 242 syntax errors project files 135, 136

IDE command line 5

MAKE

195

Resource Compiler 121

TLIB226

TLINK232

System menu:: 8

-T- BCC option (remove assembler options)

179

-t RC option (standard/386 mode) 122

It

TLINK option (default to .COM) 247

It

TLINK option (generate .COM file) 237, 247

Tab Size option 93 tables, virtual See virtual tables tabs characters printing 31 size of 93 spaces vs. 92 using in the editor 92

TASM See Turbo Assembler

TASM2MSG.EXE 77

$T ASM transfer macro 81

TCCONFIG.TC See configuration files, integrated environment

TCDEF.DPR files 22

303

TCDEF.DSK files 22

TCDEF.SYM 178,271,272, See also .SYM files

lTd and ITw TLINK options (target file) 116,

248

.TDS files 64

TDSTRIP debugging information and 64

TLINK and 249

TEML See The online document UTIL.DOC terminate and stay resident See TSR programs

Test Stack Overflow command 67 text See also editing blocks See editing, block operations copy and paste 35 cutting 35 deleting 36 entering 146 in dialog boxes 18 inserting vs. overwriting 92

Message window 81 pasting 35 restoring (in editor) 34, 35,

150

screen display of 91 screen mode See screens, operating modes selecting 33

Help window 99

THELP See The online document UTIL.DOC

32-bit code 241

13

TUNK option (80386 32-bit code) 241 threshold size far global variables setting 168 thunks See smart callbacks tilde (-) in transfer program names 75

Tile command 96 title bars 14

TKERNEL.EXE loading 159 loading and unloading 4

TLIB (librarian) 225-231 action symbols 227-228 capabilities 225 examples 231 extended dictionary (I e)

TLINK and 229 module names 227 operations 227 precedence 227 options case sensitivity (I c) 226,

230

IE 226,229

extended dictionary (Ie) 226, 229 libname226 listfile 226 operations 226 page size (lP) 229 using 226 response files using 228 syntax 226

TLINK (linker) 231-269

ACBP field and 245 assembler code and 241

.COM files and 247, 248 command-lme compiler and

240

debugging information 248 debugging information and 248 errors 258-269 executable file map generated by 244 floating-point libraries 238 graphics library and 238 initialization modules 237 invoking 232 libraries 238 memory models and 236 module definition files and 116 numeric coprocessor libraries 239 options 241 case 241 case sensitive imports (lC) 242 case sensitivity (I c) 242

.COM files (It) 237, 247

.COM files (lTd and ITw) 116,248 debugging information (Iv) 248

DLLs (lTwe) 116,248 duplicate symbols warning (I d) 242 executable files (lTd and ITw) 116,248 extended and expanded memory (ly) 249 extended dictionary (I e) 243 file extension 234, 237

Ii

(uninitialized trailing segments) 243

(source code line numbers) 243 libraries, ignoring (In) 246 line numbers (II) 243

304

Bor/and

C++

User's Guide

map files

(1m)

debugging 244 public symbols in 244 segments in 244

In

(ignore default libraries) 246 overlays

(10) 246

pack code segments

(lP) 247

Is

(map files) 244 source code line numbers

(11)

243 target files 116, 248

lTd (Windows executable) 246

lTd and ITw (target files) 116,248

32-bit assembler code and

(13) 241

tiny model .COM files

(It)

237, 247

ITw

(Windows executable) 246 uninitialized trailing segments (Ii) 243

Iv

(debugging information) 248

Windows executable (lTd and

ITw) 116,

246,248

Ix

(map files) 244

Iy

(extended and expanded memory) 249 response files 235 example 235 restrictions 249 segment limit 266 starting 232 startup code 237 syntax 232 target file options (lTd and

ITw)

116, 248

TLIB extended dictionary and 229 warnings defined 258 list 258

Windows applications and

108,240

Toggle Breakpoint command 55 hot key 12

Topic Search command

100

hot key 12

Trace Into command 42

Debug Info in OBJs option and 43 hot key

10, 12

Source Debugging command and 43 trailing segments, uninitialized 243

Transfer

See also

projects, translators command 8, 74 dialog box 74 projects and

140

programs 27 editing 75 transfer macros 75

$CAPEDIT 77

$CAPMSG 77

$COL 77

$CONFIG 77

$DEF 78 defined 76

$DEP 78

$DIR 78

DOS commands 82

$DRIVE 79

$EDNAME 79

$ERRCOL 79

$ERRLlNE 79

$ERRNAME 79

$EXENAME 79

$EXT 79 file names 76 glossary of 77 hot keys for 75 how expanded 76

$IMPLIB 79

$INC 79 instruction 77

$LIB 79

$LINE 79

$MEM 79

$NAME

$NOSWAP80

$OUTNAME80

$PRJNAME80

$PROMPT80

$RC80

$SAVEALL81

$SAVECUR81

$SA VB PROMPT 81

$TASM81

$WRITEMSG 81 transfer programs list

140

Translator option 59, 76 translators

See

projects, translators

Treat enums as ints option 61

TRIGRAPH

See

UTIL.DOC

The online document

Index

305

TSR programs shelling to DOS and 32

- Tstring

BCC option (pass string to assembler)

179

Turbo Assembler

Borland C++ command-line compiler and

163 capturing messages 77 command-line compiler and 157 default 178 invoking 163

$TASM macro 81

TLINK and 241

TurboC2.0 project files 57

Turbo Debugger described 171

Turbo Debugger for Windows

Windows applications and 46

Turbo Editor Macro Language compiler

See

The online document UTIL.DOC

TURBOC.CFG 164

25-line display 91 typefaces used in this book 2 types debugging

typographic conventions 2 u

-U BCC option (undefine) 167

-u BCC option (underscores)

170

-U MAKE option (undefine) 197 unconditional breakpoints

!undef MAKE directive 221

See

breakpoints underbars

See

underscores underscores 171 generating automatically 63,

170

Undo command 34,

150

Group Undo and 35, 93 uninitialized data segment unions format specifier 53

See

data segment inspecting 49

UNIX keywords

using 174 porting Borland C++ files to 174

306 unmatched delimiters 155

Unsigned Characters option 62

Use Tab Character option 92

User Screen

hot key 12

User Screen command 97 user-specified library files 183 utiliities

See also

The online document

VTIL.DOC utilities

MAKE 193-224 resident extended and expanded memory and 181 standalone 189

TLIB 225-231

TLINK 231-269 v

-v

and -Vn BCC options (C++ virtual tables)

182

-v BCC option (debugging information) 171

-v option (debugging information)

243

-v RC option (display compiler messages) 122

Iv

TUNK option (debugging information) 248 variable argument list

170

variables

See also

scope automatic word-aligning 167 communal 168 debugging

global far 168 header files and 64 inspecting values of 47 register 69, 172 version number information 27

-vi option (C++ inline functions) 172

Video Graphics Array Adapter (VGA) 91 virtual tables 67

32-bit pointers and 68, 182

-WD option and 128,

180

controlling 182

DLLs and 128 storing in the code segment 68, 182

-WD option and 128,

180

Borland

C++

User's Guide

-W BCC options (Windows applications) 111,

179

-W MAKE option (save options) 197

-wxxx

BeC options (warnings) 175 warnings

See also

errors

ANSI Violations 72

C++ 72, 176 command-line options 175-176 enabling and disabling 175 frequent errors 73, 175

IMPLIB 193 options 175-176 portability 71, 176 stopping on

TLINK defined 258

TLINK (list) 258 types of 71 watch expressions

See also

debuggmg adding 54 controlling 54 deleting 54, 55 editing 54 saving across sessions 94 watch window 97

Watches command 54

-WD BeC options (.DLLs with all exportables)

180

-WD BCC options (.DLLs with all exports) 113

-WDE BCC options (.DLLs with explicit exports)

180

-WDE Bee options (DLLs wIth expliCIt exports) 113

-WE BCC options (.OBJs with explicit exports)

180

WEP (function) 125 return values 126

WHELLO (Windows program)

104

compiling and linking

105

whole-word searching 37 wildcards 37

DOS 28

GREP37

MAKE and

206

Window menu 95 window number

See

windows, window number windows active 15 defined 13 cascading 96

Clipboard 36 closed 98 closing 14, 15,27, 96

Edit

See

Edit, window elements of 13

Help

See

Help, windows

Inspector 47

List 98 menu 95

Message 46, 96 moving 16, 95 next 96 open 98 opening 15, 95

Output 97 position hot key 12

Project 98

Project Notes 98

Register 98 reopening 95 resizing 15, 16, 95 scrolling 14, 15 size hot key 12 source tracking 91 swapping in debug mode 88 dual monitors and 88 tiling 96 title bar 14

User Screen 97

Watch 97 window number 14 zooming 14, 16, 96

Windows (Microsoft)

See

Microsoft Windows

Windows All Functions Exportable command

111

Windows DLL All Functions Exportable command 113

Windows DLL Explicit Functions Exported command 113

Index

307

Windows Explicit Functions Exported command 112

Windows Smart Callbacks command 112

WinMain (function)

120

return value

120

-WN Bee options (.OBJs with explicit exports)

112 word aligning integers 167

Word Alignment option 61

$WRITEMSG transfer macro 81

-WS Bee options (smart callbacks) 112,

180

-wxxx

Bee option (warnings) 175

-wxxx

Bee options (warnings) 175-176 x

-X Bee option (disable autodependency information) 171

Ix

IDE option (extended memory) 7

-x Re option (exclude include directories) 122

y

-y Bee option (line numbers) 171

-Y Bee option (overlays) 171

Iy

TLINK option (extended and expanded memory) 249

-Yo Bee option (overlays) 171 z

-Z Bee option (register usage optimization)

173 zoombox 14

Zoom command 96 hot key

10, 12

-zX options (code and data segments) 177, 178

308

Borland

C++

User's Guide

2.0

B o

L A

N D

CORPORATE HEADOUARTERS : liDO GREEN HilLS ROAD , P , O , BOX Bl0001 , SCOTTS VAllEY , CA 95087 · 0001 , 1401,431 · 5300 .

OFFICES IN : AUSTRALIA , DENMARK , FRANCE , GERMANY , ITAl y , JAPAN , SWEDEN AND THE UNITED KINGDOM. PART. 14MN · TCPOl • BOR 1'73

Dobrý den! Jsem AI chatbot speciálně vyškolený, abych vám pomohl s Borland 2.0 C++ compiler User's Guide. Důkladně jsem prošel dokument a mohu vám pomoci najít přesné informace, které potřebujete, nebo vysvětlit obsah jasně a jednoduše. Ať už hledáte pokyny ke konkrétním funkcím, kroky pro odstraňování problémů nebo obecné použití, neváhejte se zeptat. Čím více podrobností uvedete o svých obavách nebo potřebách, tím přesněji a efektivněji vám mohu pomoci!

Asistent píše

Asistent je mimo klávesnici. Zkuste to prosím později.

Zdá se, že jste narazili na dokument, který je napsán ve více jazycích, včetně jazyka, který není váš rodný. Pomocí následujících odkazů můžete dočasně skrýt stránky bez jazyka, kterému dáváte přednost.

Reklama