Copyright: Copyright © 2000 Inprise Corporation.                      All rights reserved.                                                 This Help file was compiled on   Wednesday, February 23, 2000 12:40:42.


C++Builder tools overview

C++Builder includes many tools to help you create C++ programs.

The following table lists Borland tools that come with your C++Builder package:

File	Description

BCC32.EXE	C++ compiler (32-bit), command-line version

BPR2MAK.EXE	Converts project file from XML to MAKE file format for use with command-line tools

BRC32.EXE	Resource compiler (32-bit), command-line version

BRCC32.EXE	Resource shell (32-bit)

CONVERT.EXE	Converts .DFM form files into a .TXT file format

CPP32.EXE	C preprocessor (32-bit), command-line version

DCC32.EXE	Object Pascal compiler (32-bit), command-line version

FCONVERT.EXE	Converts text files between OEM and ANSI formats

GREP.EXE	File search utility

ILINK32.EXE	Incremental linker (32-bit), command-line version

IMPDEF.EXE	Utility used when building apps with Libraries

IMPLIB.EXE	Utility used when building apps with Libraries

MAKE.EXE	Make utility

REGSRVR.EXE	Registers ActiveX and OLE server .DLLs

RLINK32.DLL	Resource linker (32-bit)

TDUMP.EXE	File dump utility

TLIB.EXE	Utility for maintaining static-link libraries

TLIBIMP.EXE	(Type Library Import) tool. Takes existing type libraries and creates C++Builder Interface files. Incorporated into the Type Library editor.

TOUCH.EXE	Change files stamps to current date/time

TRIGRAPH.EXE	Converts 3-character trigraph sequences into single characters

VCTOBPR.EXE	Converts Microsoft Visual C++ 5.0 and 6.0 project (.DSP) and workspace (.DSW) files to their equivalent Borland C++Builder files

WS32.EXE	WinSight32, 32-bit utility to watch Windows messages


Using the command-line compiler
Using the C++ command-line compiler

See also

C++Builder includes BCC32.EXE, the Borland C++ command-line compiler.

Command-line compiler syntax

The syntax for BCC32 is:

BCC32 [option [option...]] filename [filename...]

Where:

Items enclosed in brackets are optional.

option refers to the command-line options.

filename refers to the source-code files you want to compile.

To see a list of the commonly used compiler options, type BCC32 at the command line (without any options or file names), then press ENTER. This list displays the options that are enabled by default.

The command-line compiler name, each option, and the file names must all be separated by at least one space. Precede each option by either a hyphen (-) or a forward slash (/). For example:

BCC32 -Ic:\code\hfiles

Options and file names entered on the command line override settings in configuration files.

You can use BCC32 to send .OBJ files to ILINK32 or .ASM files to TASM32 (if you have TASM32 installed on your machine).

Default settings

BCC32.EXE has specific options that are on by default. To turn off a default option or to override options in a configuration file, follow the option with a minus (-) sign.

Files with the .CPP extension compile as C++ files. Files with a .C extension, with no extension, or with extensions other than .CPP, .OBJ, .LIB, or .ASM compile as C files.

The compiler tries to link with a module-definition file with the same name as the executable.


Using compiler configuration files

See also

If you repeatedly use a certain set of options, you can list them in a configuration file instead of continually typing them on the command line. A configuration file is a standard ASCII text file that contains one or more command-line options. Each option must be separated by a space or a new line.

Whenever you issue a compile command, BCC32.EXE searches for a configuration file called BCC32.CFG. The compiler looks for the .CFG file first in the directory where you issue the compile command, then in the directory where the compiler is located.

You can create and use multiple configuration files in addition to using the default .CFG file. To use a configuration file, use the following syntax where you would place the compiler options:

+[path]filename

For example, you could use the following command line to use a configuration file called MYCONFIG.CFG:

BCC32 +C:\MYPROJ\MYCONFIG.CFG mycode.cpp

Options typed on the command line override settings stored in configuration files.


Using compiler response files

See also

Response files let you list both compiler options and file names in a single file (unlike configuration files, which accept only compiler options). A response file is a standard ASCII text file that contains one or more command-line options and/or file names, with each entry in the file separated by a space or a new line. In addition to simplifying your compile commands, response files let you issue a longer command line than most operating systems allow.

The syntax for using a single response file is:

BCC32 @[path]respfile.txt

The syntax for using multiple response files is:

BCC32 @[path]respfile.txt @[path]otheresp.txt

Response files shipped with C++Builder have an .RSP extension.

Options typed at the command line override any option or file name in a response file.


Compiler option precedence rules

See also

The command-line compilers evaluate options from left to right, and follows these rules:

If you duplicate any option (except for the options -D, -U, -I, or -L), the last option typed overrides any earlier one. (-D, -U, -I, and -L are cumulative.)

Options typed at the command line override configuration and response file options.


Entering directories for command-line options

See also

C++Builder 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 (-D), allows multiple listings of a given option. Here is the syntax for these options:

-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 stack multiple entries with a single -L or -I option by using a semicolon:

BCC32.EXE -Ldirname1;dirname2;dirname3 -Iinc1;inc2;inc3 myfile.c

You can place more than one of each option on the command line, like this:

BCC32.EXE -Ldirname1 -Ldirname2 -Ldirname3 -Iinc1 -Iinc2 -Iinc3 myfile.c

You can mix listings:

BCC32.EXE -Ldirname1;dirname2 -Ldirname3 -Iinc1;inc2 -Iinc3 myfile.c

If you list multiple -L or -I options on the command line, the result is cumulative: The compiler searches all the directories listed, in order from left to right.

Note:	The C++Builder environment also supports multiple library directories. Use the Project Options and the Environment Options dialog boxes to enter the directories.


CPP32: The C compiler preprocessor

See also

CPP32.EXE produces a file that lists a C program, in which all #include files and #define macros have been expanded. While you do not need to use the preprocessor during normal compilation, you may find the list file helpful for debugging purposes.

Often, when the compiler reports an error inside a macro or an include file, you can get more information about what the error is if you can see the include files or the results of the macro expansions. In many multi-pass compilers, a separate pass performs this work, and the results of the pass can be examined. Because the Borland C++ compiler is an integrated single-pass compiler, use CPP32 to get the first-pass functionality found in other compilers.

The preprocessor has a set of command-line options which control its output. For a list of these options, type CPP32 at the command line.

For each file processed by CPP32, the output is written to a file in the current directory (or the output directory named by the -n option) with the same name as the source name but with an extension of .I.

This output file is a text file containing each line of the source file and any include files. Any preprocessing directive lines have been removed, along with any conditional text lines excluded from the compile. Unless you use a command-line option to specify otherwise, text lines are prefixed with the file name and line number of the source or include file the line came from. Within a text line, any macros are replaced with their expansion text.

The resulting output of CPP32 cannot be compiled because of the file name and line number prefix attached to each source line. However, use the -P- option to produce a file which doesn’t have line numbers. You can then pass this file to the compiler (use the -P compiler option to force a C++ compile).


Using CPP32

CPP32.EXE uses the following command-line syntax and options:

Syntax

CPP32 [ options ] file[s]

Options

The following options can be used with CPP32:

Option	Description

-Ax	Specify language extensions

-C	Allow nested comments

-Dname	Define macro

-gnnn	Stop after N warnings

-innn	Maximum identifier length N

-Ipath	Include files directory

-jnnn	Stop after N errors

-npath	Output file directory

-ofilename	Output file name

-p	Pascal calls

-P	Include source line info (on by default)

-Sc	Keep comments in preprocessed file

-Sd	Keep defines in preprocessed file

-Sk	Keep output on errors

-Sr	Make output readable by preserving comments and indentations

-Ss	Show statistics of file names and line counts

-Uname	Undefine macro

-w	Enable all warnings

-w-xxx	Disable warning xxx

-wxxx	Enable warning xxx


CPP32 as a Macro Preprocessor

The -P option tells CPP32 to prefix each line with the source file name and line number. With the -P- option, CPP32 can be used as a macro preprocessor; the resulting .I file can then be compiled with BCC32. (Note that you can also use the BCC32 option -P to set default file extensions.)

The following simple program illustrates how CPP32 preprocesses a file, first with -P selected, then with -P-.

Source file: HELLOFB.C

#define NAME "Frank Borland"

#define BEGIN {

#define END   }

main()

BEGIN

  printf("%s\n", NAME);

END

CPP32 command line:   CPP32 HELLOFB.C

Output:

HELLOFB.C 1:

HELLOFB.C 2:

HELLOFB.C 3:

HELLOFB.C 4:

HELLOFB.C 5: main()

HELLOFB.C 6: {

HELLOFB.C 7:    printf("%s\n","Frank Borland");

HELLOFB.C 8: }

CPP32 command line:   CPP32 -P- HELLOFB.C

Output:

main()

{

printf("%s\n","Frank Borland");

}


Using MIDL with CPP32.EXE

MIDL (Microsoft Interface Definition Language) is an RPC compiler. In order to use MIDL with the C++Builder preprocessor (CPP32.EXE), you must use the following MIDL command:

MIDL -cpp_cmd {CPP32} -cpp_opt "-P- -oCON {CPP32 options}" {MIDL options} {idl/.acf}

Option	Description

-cpp_cmd {CPP32}	Tells MIDL which preprocessor to use when processing an .IDL or .ACF file. MIDL calls the preprocessor to expand macros within source files.

-cpp_opt "{options}"	Specifies the command- line options for the preprocessor. The -P- removes line number and file name information from each line of the preprocessed output. The -oCON indicates that preprocessed output should go to standard output, instead of to file. The preprocessor banner and the current file that is being processed are not emitted. Including -oCON within a .CFG file processed by the preprocessor causes the banner to be emitted.

{CPP32 options}	Passes the options to CPP32.

{MIDL options}	Any MIDL command-line options.

{.idl/.acf file}	The source file that MIDL processes.


CPP32 and UUIDs

In some cases, CPP32 does not accept valid UUIDs. For example, a valid UUID statement is:

uuid(5630EAA0-CA48-1067-B320-00DD010662DB)

When CPP32 encounters 5630EAA0, it is classified as a floating-point number, and since it is an invalid floating point number, the preprocessor emits an error. To work around this problem, enclose the UUID within quotes and use the -ms_ext MIDL option. The UUID statement becomes:

uuid("5630EAA0-CA48-1067-B320-00DD010662DB")

and the MIDL command line becomes:

MIDL -ms_ext -cpp_cmd CPP32 -cpp_opt "-P- -oCON

{CPP32 options}" {MIDL options} {.idl/.acf file}


Using .CC and .CXX files

When using C++ files that have an extension other than .CPP, such as .CC or .CXX, you can use one of the following methods to ensure that these files are compiled as C++ files and not as C files.

You can create an empty .CPP and include them in this file using the #include directive:

#include "myfile.cc"

and then just add this .CPP file to your project by using the Project|Add to Project menu option.

You can also add the /P compiler switch to the OPTIONS CFLAG1 sections of the Project Options file (BPR file) and specifying the extension, as shown below. This is done by using the Project|Edit options source menu item. After you make this addition, you can then add the .CC or .CXX file to the project and it will be compiled as a would a .CPP file.

Example

<OPTIONS>

    <IDLCFLAGS value="-src_suffix cpp -D_DEBUG -I$(BCB)\include -I$(BCB)\include\vcl -boa"/>

    <CFLAG1 value="-Od -H=$(BCB)\lib\vcl50.csm -Hc -Vx -Ve -X- -r- -a8 -b- -k -y -v -vi- -c

      -tW -tWM -Pcc"/>


GREP: A Text-Search Utility

See also

GREP (Global Regular Expression Print) is a powerful text-search program derived from the UNIX utility of the same name. GREP searches for a text pattern in one or more files or in its standard input stream.

Here is a quick example of a situation where you might want to use GREP. Suppose you wanted to find out which text files in your current directory contained the string "Bob". You would type:

grep Bob *.txt

GREP responds with a list of the lines in each file (if any) that contained the string "Bob". Because GREP does not ignore case by default, the strings "bob" and "boB" do not match.

GREP can do a lot more than match a single, fixed string. You can make GREP search for any string that matches a particular pattern. (See GREP: The search string.)


GREP: Command-line Syntax

See also

The general command-line syntax for GREP is

grep [-options] searchstring [file(s) ... ]

Option	Description

options	consist of one or more letters, preceded by a hyphen (-), that changes the behavior of GREP.

searchstring	gives the pattern to search for.

file(s)	tells GREP which files to search. (If you do not specify a file, GREP searches standard input; this lets you use pipes and redirection.)

The command GREP ? prints a help screen showing the options, special characters, and defaults for GREP.

Redirecting Output from GREP

If you find that the results of your GREP are longer than one screen, you can redirect the output to a file. For example, you could use this command:

GREP "Bob" *.txt > temp.txt

which searches all files with the TXT extension in the current directory, then puts the results in a file called TEMP.TXT. (You can name this file anything you like.) Use any word processor to read TEMP.TXT (the results of the search).


GREP: Command-line Options

See also

You can pass options to the GREP utility on the command line by specifying one or more single characters preceded by a hyphen (-). Each individual character is a switch that you can turn on or off: A plus symbol (+) after a character turns the option on; a hyphen (-) after the character turns the option off. The + sign is optional; for example, -r means the same thing as -r+. You can list multiple options individually (like this: -i -d -l), or you can combine them (like this: -ild or -il, -d, and so on).

Here are the GREP option characters and their meanings:

Option	Description

-c	Count only: Prints only a count of matching lines. For each file that contains at least one matching line, GREP prints the file name and a count of the number of matching lines. Matching lines are not printed. This option is off by default.

-d	Search subdirectories: For each file specified on the command line, GREP searches for all files that match the file specification, both in the directory specified and in all subdirectories below the specified directory. If you give a file without a path, GREP assumes the files are in the current directory. This option is off by default.

-e	Search expression follows: Indicates that the next argument is the search expression. This option is useful when you want to search for an expression that begins with “-“.

-i	Ignore case: GREP ignores upper/lowercase differences. When this option is on, GREP treats all letters a to z as identical to the corresponding letters A to Z in all situations. This option is off by default.

-l	List file names only: Prints only the name of each file containing a match. After GREP finds a match, it prints the file name and processing immediately moves on to the next file. This option is off by default.

-n	Line numbers: Each matching line that GREP prints is preceded by its line number. This option is off by default.

-o	UNIX output format: Changes the output format of matching lines to support more easily the UNIX style of command-line piping. All lines of output are preceded by the name of the file that contained the  matching line. This option is off by default.

-r	Regular expression search: The text defined by searchstring is treated as a regular expression instead of as a literal string. This option is on by default. A regular expression is one or more occurrences of one or more characters optionally enclosed in quotes. The following symbols are treated specially:

^  start of line	$  end of line

.  any character	\  quote next character

*  match zero or more	+  match one or more

[aeiou0-9]	match a, e, i, o, u, and 0-9

[^aeiou0-9]	match all but a, e, i, o, u, and 0-9

-u filename	Update options: Creates a copy of GREP.EXE called filename.EXE.  Any options included on the command line are saved as defaults in the new copy of GREP. Use the -u option to customize the default option settings. To verify that the defaults have been set correctly, type filename ?; each option on the help screen is followed by a + or – to indicate its default setting.

-v	Nonmatch: Prints only nonmatching lines. Only lines that do not contain the search string are considered nonmatching lines. This option is off by default.

-w	Word search: Text found that matches the regular expression is considered a match only if the character immediately preceding and following cannot be part of a word. The default word character set includes A to Z, 0 to 9, and the underscore ( _ ). This option is off by default. An alternate form of this option lets you specify the set of legal word characters. Its form is -w[set], where set is any valid regular expression.

If you define the set with alphabetic characters, it is automatically defined to contain both the uppercase and lowercase values for each letter in the set (regardless of how it is typed), even if the search is case-sensitive. If you use the -w option in combination with the -u option, the new set of legal characters is saved as the default set.

-z	Verbose: GREP prints the file name of every file searched. Each matching line is preceded by its line number. A count of matching lines in each file is given, even if the count is zero. This option is off by default.

?	Displays a help screen showing the options, special characters, and defaults for GREP.


GREP: The Search String

See also

The value of searchstring defines the pattern GREP searches for. A search string can be either a regular expression or a literal string.

In a regular expression, certain characters have special meanings: They are operators that govern the search.

In a literal string, there are no operators: Each character is treated literally.

You can enclose the search string in quotation marks to prevent spaces and tabs from being treated as delimiters. To search for an expression that begins with “-“, use the -e option. The text matched by the search string cannot cross line boundaries; that is, all the text necessary to match the pattern must be on a single line.

A regular expression is either a single character or a set of characters enclosed in brackets. A concatenation of regular expressions is a regular expression.

When you use the -r option (on by default), the search string is treated as a regular expression (not a literal expression). The following characters have special meanings:

Symbol	Description

 ^	A circumflex at the start of the expression 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.

 *	An asterisk after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo* matches bot, boo, and as well as bo.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.

{ }	Characters or expressions in braces are grouped so that the evaluation of a search pattern can be controlled and so grouped text can be referred to by number.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

  \  	A backslash before a wildcard character tells GREP to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.

Four of the "special" characters ($, ., *, and +) do not have any special meaning when used within a bracketed set. In addition, the character ^ is only treated specially if it immediately follows the beginning of the set definition (immediately after the [ delimiter).


GREP: File Specifications

See also

The files option tells GREP which files to search. Files can be an explicit file name or a generic file name  incorporating the DOS ? and * wildcards. In addition, you can type a path (drive and directory information). If you list files without a path, GREP searches the current directory. If you do not specify any files, input to GREP must come from redirection (<) or a vertical bar (|).


GREP: Examples

See also

These examples show how to combine the features of GREP to do different kinds of searches. They assume default settings for GREP are unchanged.

grep -r "[^a-z]main\ *\(" *.c

grep -ri [a-c]:\\data\.fil *.c *.inc

grep "search string with spaces" *.doc *.c

grep -rd "[ ,.:?'\"]"$ \*.doc

grep -w[=] = *.c


GREP: Example 1

See also

Command

grep -r "[^a-z]main\ *\(" *.c

Matches

main(i,j:integer)

if (main  ()) halt;

if (MAIN  ()) halt;

Does Not Match

mymain()

Explanation

The search string tells GREP to search for the word main with no preceding lowercase letters ([^a-z]), followed by zero or more occurrences of blank spaces (\ *), then a  left parenthesis. Since spaces and tabs are normally  considered command-line delimiters, you must quote them if you want to include them as part of a regular expression.


GREP: Example 2

See also

Command

grep -ri [a-c]:\\data\.fil *.c *.inc

Matches

A:\data.fil

B:\DATA.FIL

c:\Data.Fil

Does Not Match

d:\data.fil

a:data.fil

Explanation

Because the backslash (\) and period (.) characters usually have special meaning in path and file names, you must place the backslash escape character  immediately in front of them if you want to search for them. The -i option is used here, so the search is not case sensitive.


GREP: Example 3

See also

Command

grep "search string with spaces" *.doc *.c

Matches

This is a search string with spaces in it.

Does Not Match

This search string has spaces in it.

Explanation

This is an example of how to search for a string with embedded spaces.


GREP: Example 4

See also

Command

grep -rd "[ ,.:?'\"]"$ \*.doc

Matches

He said hi to me.

Where are you going?

In anticipation of a unique situation,

Examples include the following:

"Many men smoke, but fu man chu."

Does Not Match

He said "Hi" to me

Where are you going? I'm headed to the

Explanation

This example searches for any one of the characters " . : ? ' and , at the end of a line. The double quote within the range is preceded by an escape character so it is treated as a normal character instead of as the ending quote for the string. Also, the $ character appears outside of the quoted string. This demonstrates how regular expressions can be concatenated to form a longer expression.


GREP: Example 5

See also

Command

grep -w[=] = *.c

Matches

i = 5;

j=5;

i += j;

Does Not Match

if (i == t) j++;

/* =================== */

Explanation

This example redefines the current set of legal characters for a word as the assignment operator (=) only, then does a word search. It matches C assignment statements, which use a single equal sign (=), but not equality tests, which use a double equal sign (==).


Using COFF2OMF
Using the COFF2OMF import library conversion tool

See also

Coff2Omf is a command line tool that converts a COFF import library file (InputFile) to a corresponding OMF import library file (OutputFile). Coff2Omf.exe is located in the C++Builder BIN directory.  The syntax is:

Coff2Omf [options] InputFile OutputFile

Coff2Omf converts the publicly exported symbols in the COFF import library to a corresponding set of symbols in the OMF import library.  Coff2Omf  enables C++Builder users to link to Microsoft and other third-party DLLs that use the COFF format. Coff2Omf does not convert .OBJ files.

Run the Coff2Omf tool on a COFF import library created for a specific DLL, and use the resulting import library to link OMF format EXEs and DLLs to the COFF DLL. The switches for Coff2Omf are:

-q - Quiet mode (converts without writing tool and copyright information to standard output)

-v - Dump of selected symbols (dumps the symbols that have been converted to standard output which can be redirected to an output file)

-d - Delete output file if empty (deletes the output file there is an error and the conversion results in an empty file)

-h, -?  Display help

-r - Remove (delete) output file if empty

-lib:xx Specify options for OMF import library generation:

xx can be:

•	ms - Allow entries that have MS C++ name mangling (default: no)

•	st - Normalize names instead of aliasing MS stdcall mangling

•	ca - Don't perform MS cdecl aliasing (default is to alias)


Using IMPLIB

See also

The IMPLIB utility creates import library. IMPLIB takes as input DLLs, module definition files, or both, and produces an import library as output.

If you've created a Windows application, you've already used at least one import library, IMPORT32.LIB, the import library for the standard Windows DLLs. IMPORT32.LIB is linked automatically when you build a Win32 application in the C++Builder IDE and when using BCC32 at the command line.

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).

Creating an Import Library for a DLL

Options must be lowercase and preceded by either a hyphen or a slash.

Type:

IMPLIB Options LibName [ DefFiles... | DLLs... ] [@ResponseFile]

where Options is an optional list of one or more IMPLIB options, LibName 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.

You can also use a response file to list the .DEF and .DLL files that you want to process. A response file is an ACSII text file that contains a list of files. The files must be separated by either spaces or new lines in the file. To specify a response file on the command line, precede the response filename with an "at" sign (@). For example,

implib  foo.lib  @respon.txt

Note:	A DLL can also have an extension of .EXE or .DRV, not just .DLL.

Option	Description

-a	Add '_' alias for cdecl functions for compatibility with Microsoft libraries

-c	Warnings on case sensitive symbols

-f	Force imports by name

-w	No warnings.


Using the module definition file manager (IMPDEF)

See also

Import libraries provide access to the functions in a Windows DLL.

IMPDEF takes as input a DLL name, and produces as output a module definition file with an export section containing the names of functions exported by the DLL.

The syntax is:

IMPDEF DestName.DEF SourceName.DLL

This creates a module definition file named DestName.DEF from the file SourceName.DLL. The resulting module definition file would look something like this:

LIBRARY     FileName

DESCRIPTION 'Description'

EXPORTS

            ExportFuncName              @Ordinal

        .

        .

        .

            ExportFuncName              @Ordinal

where:

FileName is the DLL's root file name

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

Ordinal is that function's ordinal value (an integer).

Option	Description

-a	Add '_' alias for cdecl functions for compatibility with Microsoft libraries

-h	Emit hints


Classes in a DLL

See also

IMPDEF is useful for a DLL that uses C++ classes. If you use the __declspec (or _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, and automatically includes the member functions and static data members.

Since the names of these functions are mangled, it would be tedious to list them all in the EXPORTS section of a module definition file simply to 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. If the exported name is mangled, IMPDEF will also include that function's unmangled, original name as a comment following the function entry. So, for instance, the module definition file created by IMPDEF for a DLL that used C++ classes would look something like this:

LIBRARY     FileName

DESCRIPTION 'Description'

EXPORTS

            MangledExportFuncName  @Ordinal ; ExportFuncName

        .

        .

        .

            MangledExportFuncName  @Ordinal ; ExportFuncName

where

FileName is the DLL's root file name

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)

ExportFuncName gives the function's original name.


Functions in a DLL

See also

IMPDEF creates an editable source file that lists all the exported functions in the DLL. You can edit this .DEF file to contain only those functions that you want to make available to a particular application, then run IMPLIB on the edited .DEF file. This results in an import library that contains import information for a specific subset of a DLL's export functions.

Suppose you're distributing a DLL that provides functions to be used by several applications. Every export function in the DLL is defined with __declspec (or _export). Now, if all the applications used all the DLL's exports, then you could use IMPLIB to make one import library for the DLL. You could deliver that import library with the DLL, and it 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.

But suppose you want to give only a few 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 provides import information only 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, remove the EXPORTS section entries for those functions you don't want in the customized import library, and then 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.


Using TLIB

See also

When it modifies an existing library, TLIB always creates a copy of the original library with a .BAK extension.

Build or Modify Libraries

The libraries included with C++Builder were built with TLIB. You can use TLIB to build your own libraries, or to modify the C++Builder libraries, your libraries, libraries furnished by other programmers, or commercial libraries you've 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.

TLIB can also create (and include in the library file) an extended dictionary, which can be used to speed up linking.

Although TLIB is not essential for creating executable programs with C++Builder, it is a useful programming productivity tool that can be indispensable for large development projects.


TLIB Command-line Options

See also

The TLIB command line takes the following general form, where items listed in square brackets are optional:

tlib [@respfile] [option] libname [operations] [, listfile]

TLIB options

For an online summary of TLIB options, type TLIB and press Enter.

Option	Description

@respfile	The path and name of the response file you want to include. You can specify more than one response file.

libname	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. Use only the .LIB extension because both BCC32 and the IDE require the .LIB extension in order to recognize library files. Note: If the named library does not exist and there are add operations, TLIB creates the library.

/a	Adds a series of files to the library

/C	The case-sensitive flag. This option is not normally used.

/d	Deletes a series of files from the library.

/e	Extracts a series of files from the library without removal.

/u	Updates a series of files in the library

/Psize	Sets the library page size to size.

/0	Purges comment records.

operations	The list of operations TLIB performs. Operations can appear in any order. If you only want to examine the contents of the library, don't give any operations.

listfile	The name of the file that lists library contents. The listfile name (if given) must be preceded by a comma. No listing is produced if you don't give a file name. 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 is .LST. You can direct the listing to the screen by using the listfile name CON, or to the printer by using the name PRN.


Using TLIB Response Files

See also

When you use a large number of operations, or if you find yourself repeating certain sets of operations over and over, you will probably want to use response files. A response file is an ASCII text file (which can be created with the Borland C++ editor) that contains all or part of a TLIB command. Using TLIB response files, you can build TLIB commands larger than would fit on one command line. Response files can

Contain more than one line of text; use the ampersand character (&) at the end of a line to indicate that another line follows.

Include a partial list of commands. You can combine options from the the command line with options in a response file.

be used with other response files in a single TLIB command line.


TLIB /C Option

See also

Using Case-sensitive Symbols in a Library

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 a module to the library that duplicates a symbol, TLIB displays an error message and doesn't add the module.

Normally, when TLIB checks for duplicate symbols in the library, uppercase and lowercase letters are not treated differently (for example, the symbols lookup and LOOKUP are treated as duplicates). You can use the /C option to add a module to a library that includes symbols differing only in case.

Don't use /C if you plan to use the library with other linkers or let other people use the library.

TLIB normally rejects symbols that differ only in case because some linkers aren't case-sensitive. ILINK32 has no problem distinguishing uppercase and lowercase symbols. As long as you use your library only with ILINK32, you can use the TLIB /C option without any problems.


TLIB /e Option

See also

Extracting a series of files from a library

Extracts a series of


TLIB /P Option

See also

Setting the Page Size to Create a Large Library

The library page size determines the maximum combined size of all object modules in the library, which 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, use the /P option to increase the page size. The page size must be a power of 2, and it cannot 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), an average of 16 bytes will be lost per object module 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 /P with the next available higher page size.


TLIB /a Option

See also

Adding a series of files to a library

TLIB adds the named files to the library. If the files have no extension, TLIB assumes an extension if .OBJ. If the files are libraries (with a .LIB extension), then the operation adds all of the modules in the named libraries to the target library.

If a module or modules being added already exist, TLIB displays a message and does not add the new module or modules.


TLIB /u Option

See also

Updating a series of files from a library

TLIB updates the named files to the library. If the files have no extension, TLIB assumes an extension if .OBJ. If the files are libraries (with a .LIB extension), then the operation updates all of the modules in the named libraries to the target library.


TLIB /d Option

See also

Removing a series of files from a library

TLIB removes the named module or modules from the library. If the module or modules do not exist in the library, TLIB displays a message.

A remove operation needs only module names. TLIB lets you enter a full path name with drive and extension included, but ignores everything except the module name.


Operation List

See also

The operation list describes what actions you want TLIB to do and 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 DOS's COMMAND.COM-imposed line-length limit of 127 characters. The order of the operations is not important. TLIB always applies the operations in a specific order:

To replace a module, remove it, then add the replacement module.

1.	All extract operations are done first.

2.	All remove operations are done next.

3.	All add operations are done last.

TLIB finds the name of a module by stripping any drive, path, and extension information from the given file name.

Note that TLIB always assumes reasonable defaults. For example, to add a module that has an .OBJ extension from the current directory, you need to supply only the module name, not the path and .OBJ extension.

Wildcards are never allowed in file or module names.

TLIB recognizes three action symbols (*, +, -), which you can use singly or combined in pairs for a total of five distinct operations. The order of the characters is not important for operations that use a pair of characters. The action symbols and what they do are listed here:

To create a library, add modules to a library that does not yet exist.

TLIB action symbols

Symbol 	Name	Description

+	Add	TLIB adds the named file to the library. If the file has no extension, 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	TLIB removes the named module from the library. If the module does not exist in the library, TLIB displays a message.

A remove operation needs only a module name. TLIB lets you enter a full path name with drive and extension included, but ignores everything except the module name.

*	Extract	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.

You can't directly rename modules in a library. To rename a module, extract and remove it, rename the file just created, then add it back into the library.

-*	Extract &	TLIB copies the named module to the corresponding

*-	Remove	TLIB removes the file name and then removes it from the library.

-+	Replace	TLIB replaces the named module with the corresponding file.


TLIB Examples

These simple examples demonstrate some of the different things you can do with TLIB:

Example 1

To create a library named MYLIB.LIB with modules X.OBJ, Y.OBJ, and Z.OBJ, type:

tlib mylib +x +y +z.

Example 2

To create a library named MYLIB.LIB and get a listing in MYLIB.LST too, type:

tlib mylib +x +y +z, mylib.lst.

Example 3

To get a listing in CS.LST of an existing library CS.LIB, type:

tlib cs, cs.lst.

Example 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.

Example 5

To extract module Y.OBJ from MYLIB.LIB and get a listing in MYLIB.LST, type:

tlib mylib *y, mylib.lst.

Example 6

To create a new library named ALPHA, with modules A.OBJ, B.OBJ, ..., G.OBJ using a response file:

1.	First create a text file, ALPHA.RSP, with

+a.obj +b.obj +c.obj &

      +d.obj +e.obj +f.obj &

      +g.obj

2.	Then use the TLIB command, which produces a listing file named ALPHA.LST:

tlib alpha @alpha.rsp, alpha.lst

Example 7

To update modules Y.OBJ and Z.OBJ and delete modules A.OBJ and B.OBJ from MYLIB.LIB

tlib mylib /u Y.obj Z.obj /d A.obj B.obj


Using TLIBIMP

The TLIBIMP creates a import type library for ActiveX controls, OLE servers, or COM servers. TLIBIMP uses a file name TLIBIMP.SYM that provides custom mapping for some type libraries. See below for further information on this file. This file must be in the same directory as TLIBIMP.EXE.

Creating an Type library

Options must be lowercase and preceded by either a hyphen or a slash.

Type:

TLIBIMP [Options] <typelibfile> [Switches]

where Options is an optional list of one or more TLIBIMP options, TypeLibName is the name of the ActiveX control,OLE server, or COM server, and Switches controls the output

Option	Description

-A<suffix>	Type Library file suffix

-B<suffix>	OCX/Server file suffix

-D<path>	Output directory

-F<filename>	Type Library output filename

-N<namespace>	C++ namespace

-X<filename>	OCX wrappers Output filename

The list of options available to TLIBIMP

Switch	Description

-C	Generate C++ import file

-E	Generate wrapper class for Dispinterfaces (C++ only)

-G	Expose namespace with the using statement

-H	Generate IDE component wrappers for ActiveX Controls

-I	Generate IDL source file

-J	Generate CORBA IDL source file

-K	Generate Pascal CORBA stubs and skeletons

-L	Generate IDE component wrappers for OLE servers

-O	Generate COClass Creator wrappers

-P	Generate Pascal import file

-Q	Generate Register function for IDE component wrappers

-R	Generate files for dependent type libraries

-V	Generate Event wrappers for server (C++ only)

-W	Warnings in import file

-Yh	Ignore the [Hidden] flag when importing

-Yr	Ignore the [Restricted] flag when importing

-Yp	Ignore the [PreDecID] flag when importing

-Ya	Combine the –Yh –Yr –Yp options

-@	Always use the dispinterfaces in control wrappers (C++ only)

Mapping symbol names in the type library

When importing type libraries in C++Builder 5, custom mapping for some type libraries is specified in tlibimp.sym and may differ from code generation in previous releases. For example, when doing Microsoft Word automation, the symbol that used to be CoApplication_ is now CoWordApplication.

In previous releases, when new type libraries were added using an existing identifier, an underscore was added to distinguish the identifier. So, the identifier called Application became Application_. Multiple underscores might be added if another imported type library used the same identifier.

C++Builder 5 provides the ability to map symbol names in the type library within the tlibimp.sym file located in the BIN directory. The tlibimp.sym file contains mapping for some common applications including Microsoft Word, Microsoft Excel, Microsoft PowerPoint, and Microsoft Access. If you have applications that use these servers, you may have conflicts when compiling them in C++Builder 5.

The following example shows how symbol names are remapped in Microsoft Word. The first line (after the comment) specifies the GUID (globally unique identifier) of the server in the registry.

Example

[{00020905-0000-0000-C000-000000000046}:TypeNames]

The rest of the lines remap keys to new values (instead of just adding an underscore to conflicting identifiers). For example,

Application=WordApplication

Example remapping for Microsoft Word

;;==============================================;;

;; Map WinWord CoClasses to better names        ;;

;;==============================================;;

[{00020905-0000-0000-C000-000000000046}:TypeNames]

Application=WordApplication

Document=WordDocument

Font=WordFont

ParagraphFormat=WordParagraphFormat

OLEControl=WordOLEControl

LetterContent=WordLetterContent

You can map conflicting symbols for other servers whose type libraries you want to import by using the same format as shown for the example above.

Note:	Be careful when editing tlibimp.sym. Do not change remapping that occurs for C++ or Pascal member or type names at the beginning of the file.


IMPLIB

IMPLIB creates import libraries, and IMPDEF creates module definition files (.DEF files). Import libraries and module definition files provide information to the linker about functions imported from dynamic-link libraries (DLLs).


TLIB

TLIB is a utility that manages libraries of individual .OBJ (object module) files. A library is a convenient tool for dealing with a collection of object modules as a single unit.


Import Libraries

Import libraries contain records. Each record contains the name of a DLL, and specifies where in the DLL the imported functions reside. These records are bound to the application by  the linker and provide Windows with the information necessary to resolve DLL function calls. An import library can be substituted for part or all of the IMPORTS section of a module definition file.


IMPDEF

IMPDEF takes as input a DLL name, and produces as output a module definition file with an export section containing the names of functions exported by the DLL.


Using MAKE

See also

MAKE.EXE is a command-line utility that helps you manage project compilation and link cycles. MAKE is not inherently tied to compiling and linking, but is a more generic tool for executing commands based on file dependencies. MAKE helps you quickly build projects by compiling only the files you have modified since the last compilation. In addition, you can set up rules that specify how MAKE should deal with the special circumstances in your builds.

MAKE Basics

MAKE uses rules you write along with its default settings to determine how it should compile the files in your project. For example, you can specify when to build your projects with debug information and to compile your .OBJ files only if the date/time stamps of a source file is more recent than the .OBJ itself. If you need to force the compilation of a module, use TOUCH.EXE to modify the time stamp of one of the module’s dependents.

In an ASCII makefile, you write explicit and implicit rules to tell MAKE how to treat the files in your project; MAKE determines if it should execute a command on a file or set of files using the rules you set up. Although your commands usually tell MAKE to compile or link a set of files, you can specify nearly any operating system command with MAKE.

The general syntax for MAKE is

MAKE [options...] [target[target]]

options

are MAKE options that control how MAKE works

target

is the name of the target listed in the makefile that you want to build

You must separate the MAKE command and the options and target arguments with spaces. When specifying targets, you can use wildcard characters (such as * and ?) to indicate multiple files. To get command-line help for MAKE, type MAKE -?.


Default MAKE actions

When you issue a MAKE command, MAKE looks for the file BUILTINS.MAK, which contains the default rules for MAKE (use the -r option to ignore the default rules). MAKE looks for this file first in the current directory, then in the directory where MAKE.EXE is stored. After loading BUILTINS.MAK, MAKE looks in the current directory for a file called MAKEFILE or MAKEFILE.MAK (use the -f option to specify a file other than MAKEFILE). If MAKE can’t find either of these files, it generates an error message.

After loading the makefile, MAKE tries to build only the first explicit target listed in the makefile by checking the time and date of the dependent files of the first target. If the dependent files are more recent than the target file, MAKE executes the commands to update the target.

If one of the first target’s dependent files is used as a target elsewhere in the makefile, MAKE checks that target’s dependencies and builds it before building the first target. This chain reaction is called a linked dependency.

If something during the build process fails, MAKE deletes the target file it was building. Use the .precious directive if you want MAKE to keep the target when a build fails.

You can stop MAKE after issuing the MAKE command by pressing Ctrl+Break or Ctrl+C.


BUILTINS.MAK

The file BUILTINS.MAK contains standard rules and macros that MAKE uses when it builds the targets in a makefile. To ignore this file, use the -r MAKE option.

Here is the default text of BUILTINS.MAK:

#

# Borland C++ - (C) Copyright 1997 by Borland International

#

CC       = bcc32

RC       = brcc32

AS       = tasm32

.asm.obj:

      $(AS) $(AFLAGS) $&.asm

.c.exe:

      $(CC) $(CFLAGS) $&.c

.c.obj:

      $(CC) $(CFLAGS) /c $&.c

.cpp.exe:

      $(CC) $(CFLAGS) $&.cpp

.cpp.obj:

      $(CC) $(CPPFLAGS) /c $&.cpp

.rc.res:

      $(RC) $(RFLAGS) /r $&

.SUFFIXES: .exe .obj .asm .c .res .rc

!if !$d(BCEXAMPLEDIR)

BCEXAMPLEDIR = $(MAKEDIR)\..\EXAMPLES

!endif


About makefiles

A makefile is an ASCII file that contains the set of instructions that MAKE uses to build a certain project. Although MAKE assumes your makefile is called MAKEFILE or MAKEFILE.MAK, you can specify a different makefile name with the -f option.

MAKE either builds the target(s) you specify with the make command or it builds the first target it finds in the makefile To build more than a single target, use a symbolic target in your makefile.

Makefiles can contain

Comments (precede with a number sign [#])

Explicit and implicit rules

Macros

Directives


Symbolic targets

A symbolic target forces MAKE to build multiple targets in a makefile. When you specify a symbolic target, the dependency line lists all the targets you want to build (a symbolic target basically uses linked dependencies to build more than one target).

For example, the following makefile uses the symbolic target AllFiles to build both FILE1.EXE and FILE2.EXE:

AllFiles: file1.exe file2.exe  #Note that AllFiles has no commands

file1.exe: file1.obj

    bcc32 file1.obj

file2.exe: file2.obj

    bcc32 file2.obj

Rules for symbolic targets

Observe the following rules when you use symbolic targets:

Do not type a line of commands after the symbolic target line.

A symbolic target must have a unique name; it cannot be the name of a file in your current directory.

Symbolic target names must follow the operating system rules for naming files.


MAKE options

You can use command-line options to control the behavior of MAKE. MAKE options are case-sensitive and must be preceded with either a hyphen (-) or slash (/).

The general syntax for MAKE is

MAKE [options...] [target[target]]

options

are MAKE options that control how MAKE works

target

is the name of the target listed in the makefile that you want to build

You must separate the MAKE command and the options and target arguments with spaces. When specifying targets, you can use wildcard characters (such as * and ?) to indicate multiple files. To get command-line help for MAKE, type MAKE -?.

For example, to use a file called PROJECTA.MAK as the makefile, type MAKE -fPROJECTA.MAK. Many of the command-line options have equivalent directives that you can use within the makefile.

Option	Description

-a	Checks dependencies of include files and nested include files associated with .OBJ files and updates the .OBJ if the .h file changed. See also -c.

-B	Builds all targets regardless of file dates.

-c	Caches autodependency information, which can improve MAKE speed. Use with -a. Do not use this option if MAKE modifies include files (which can happen if you use TOUCH in the makefile or if you create header or include files during the MAKE process).

-Dmacro	Defines macro as a single character, causing an expression !ifdef macro written in the makefile to return true.

[-D]macro=[string]	Defines macro as string. If string contains any spaces or tabs, enclose string in quotation marks. The -D is optional.

-ddirectory	Specifies the drive and directory that MAKER (the real mode version of MAKE) uses when it swaps out of memory. This option must be used with -S. MAKE ignores this option.

-e	Ignores a macro if its name is the same as an environment variable (MAKE uses the environment variable instead of the macro).

-ffilename	Uses filename or filename.MAK instead of MAKEFILE (a space after -f is optional).

-h or -?	Displays MAKE options. Default settings are shown with a trailing plus sign.

-Idirectory	Searches for include files in the current directory first, then in directory you specify with this option.

-i	Ignores the exit status of all programs run from the makefile and continues the build process.

-l	Enables the use of long comment lines (on by default).

-K	Keeps temporary files that MAKE creates (MAKE usually deletes them).

-m	Displays the date and time stamp of each file as MAKE processes it.

-N	Causes MAKE to mimic Microsoft's NMAKE.

-n	Prints the MAKE commands but does not perform them, this is helpful for debugging makefiles.

-p	Displays all macro definitions and implicit rules before executing the makefile.

-q	Returns 0 if the target is up-to-date and nonzero if it is not (for use with batch files).

-r	Ignores any rules defined in BUILTINS.MAK.

-S	Swaps MAKER out of memory while commands are executed, reducing memory overhead and allowing compilation of large modules. MAKE ignores this option.

-s	Suppresses onscreen command display (silent).

-Umacro	Undefines the previous macro definition of macro.

-Wfilename	Writes MAKE to filename, updating all non-string options.


Using temporary response files
 AUsing temporary response files

MAKE can create temporary response files when your command lines become too long to place on a single line.

To begin writing to a response file, place the MAKE operator && followed by a delimiter of your choice (| makes a good delimiter) in the makefile. To finish writing to the file, repeat your delimiter.

The following example shows &&| instructing MAKE to create a file for the input to ILINK32.

prog.exe: A.obj B.obj

    ILINK32 /c @&&|     # &&| opens temp file, @ for ILINK32

    c0s.obj $**

    prog.exe

    prog.map

    maths.lib cs.lib

|                       # | closes temp file, must be on first column

The response file created by &&| contains these instructions:

c0s.obj a.obj b.obj

prog.exe

prog.map

maths.lib cs.lib

MAKE names temporary file starting at MAKE0000.@@@, where the 0000 increments by one with each temporary file you create. MAKE later deletes the temporary file when it terminates.


Using TOUCH

TOUCH.EXE updates a file's date stamp so that it reflects your system’s current time and date.

Sometimes you may need to force a target to be recompiled or rebuilt even though you haven't changed its source files. One way to do this is to use the TOUCH utility to update the time stamp of one or more of the target’s dependency files. To touch a file (or files), type the following at the command prompt:

touch [options] filename [filename...]

If TOUCH cannot find a file that matches the name you specify, it creates a zero-length file with the correct date stamp. To suppress automatic file creation, use the -c option.

Because TOUCH is a 32-bit executable, it accepts long file names. In addition, you can use file names that contain the wildcard characters * and ? to “touch” more than a single file at a time. Use the -s option to update matching files in all subdirectories.

Note:	Before you use TOUCH, make sure your system's internal clock is set correctly.

TOUCH options

TOUCH.EXE supports several command-line options:

Option	Description

-c	Don’t generate file if it doesn’t already exist.

-dmm-dd-yy	Sets the date of the file to the specified date.

-rfilename	Sets the time and date of files to match those of filename.

-h	Displays help information (same as typing TOUCH without options or file names).

-s	Recurses through subdirectories

-thh:mm:ss	Sets the time of the file to the specified time.

-v	Verbose mode. Shows each file TOUCHed.


Compatibility with Microsoft's NMAKE

Use the -N option if you want to use a makefile that was originally created for Microsoft's NMAKE. The following changes occur when you use -N:

The $d macro is treated differently, use !ifdef or !ifndef instead.

Macros that return paths won't return the last \. For example, if $(<D) normally returns C:\CPP\, the -N option causes MAKE to return C:\CPP.

Unless there's a matching .suffixes directive, MAKE begins searching for rules from the bottom of the makefile and works its way to the top.

In implicit rules, MAKE expands $* macros to the target name instead of to the dependent name.

MAKE interprets the << operator to generate temporary files, much as it would for the && operator. MAKE uses temporary files as response files. These files are then deleted. To keep a file, either use the -K MAKE command-line option (which is set automatically by -N) or use KEEP in the makefile.

<<FileName.Ext

    text

    ...

    <<KEEP

If you don't want to keep a temporary file, type NOKEEP or type only the temporary (optional) file name. If you don't type a file name, MAKE creates a name for you. If you use NOKEEP, it will override the -K command-line option.

The __NMAKE__ macro is defined. This macro creates conditionalized definitions of CPP and CXX in Builtins.mak.


Explicit and implicit rules

You write explicit and implicit rules to instruct MAKE how to build the targets in your makefile. In general, these rules are defined as follows:

Explicit rules are instructions for specific files.

Implicit rules are general instructions for files without explicit rules.

All the rules you write follow this general format:

Dependency line

    Command line

While the dependency line has a different syntax for explicit and implicit rules, the command line syntax stays the same for both rule types.

MAKE supports multiple dependency lines for a single target, and a single target can have multiple command lines. However, only one dependency line should contain a related command line. For example:

Target1: dependent1 dep2 dep3 dep4 dep5

Target1: dep6 dep7 dep8

    bcc32 -c $**


Explicit rule syntax

Explicit rules specify the instructions that MAKE must follow when it builds specific targets. Explicit rules name one or more targets followed by one or two colons. One colon means one rule is written for the target(s); two colons mean that two or more rules are written for the target(s).

Explicit rules follow this syntax:

target [target...]:[:][{path}] [dependent[s]...]

    [commands]

target

specifies the name and extension of the file to be built (a target must begin a line in the makefile-you cannot precede the target name with spaces or tabs). To specify more than one target, separate the target names with spaces or tabs. Also, you cannot use a target name more than once in the target position of an explicit rule.

path

is a list of directories that tells MAKE where to find the dependent files. Separate multiple directories with semicolons and enclosed the entire path specification in braces.

dependent

is the file (or files) whose date and time MAKE checks to see if it is newer than target. Each dependent file must be preceded by a space. If a dependent appears elsewhere in the makefile as a target, MAKE updates or creates that target before using the dependent in the original target (this in known as a linked dependency).

commands

are any operating system command or commands. You must indent the command line by at least one space or tab, otherwise they are interpreted as a target. Separate multiple commands with spaces.

If a dependency or command line continues on the following line, use a backslash (\) at the end of the first line to indicate that the line continues. For example,

MYSOURCE.EXE: FILE1.OBJ\          #Dependency line

    FILE3.OBJ                     #Dependency line continued

    bcc32 file1.obj file3.obj     #Command line

Single targets with multiple rules

A single target can have more than one explicit rule. To specify more than a single explicit rule, use a double colon (::) after the target name. The following example shows targets with multiple rules and commands.

.cpp.obj:

    bcc32 -c -ncobj $<

.asm.obj:

    tasm  /mx $<, asmobj\

mylib.lib :: f1.obj f2.obj  #double colon specifies multiple rules

    echo Adding C files

    tlib mylib -+cobjf1 -+cobjf2

mylib.lib :: f3.obj f4.obj

    echo Adding ASM files

    tlib mylib -+asmobjf3 -+asmobjf4


Implicit rule syntax

An implicit rule specifies a general rule for how MAKE should build files that end with specific file extensions. Implicit rules start with either a path or a period. Their main components are file extensions separated by periods. The first extension belongs to the dependent, the second to the target.

If implicit dependents are out-of-date with respect to the target, or if the dependents don't exist, MAKE executes the commands associated with the rule. MAKE updates explicit dependents before it updates implicit dependents.

Implicit rules follow this basic syntax:

[{source_dir}].source_ext[{target_dir}].target_ext:

    [commands]

source_dir

specifies the directory (or directories) containing the dependent files. Separate multiple directories with a semicolon.

.source_ext

specifies the dependent filename extension.

target_dir

specifies the directory where MAKE places the target files. The implicit rule will only be used for targets in this directory. Without specifying a target directory, targets from any directory will match the implicit rule.

.target_ext

specifies the target filename extension. Macros are allowed here.

: (colon)

marks the end of the dependency line.

commands

are any operating system command or commands. You must indent the command line by at least one space or tab, otherwise they are interpreted as a target.

If two implicit rules match a target extension but no dependent exists, MAKE uses the implicit rule whose dependent's extension appears first in the .SUFFIXES list.

Explicit rules with implicit commands

A target in an explicit rule can get its command line from an implicit rule. The following example shows an implicit rule followed by an explicit rule without a command line.

.c.obj:

    bcc32 -c $<   #This command uses a macro $< described later

myprog.obj:       #This explicit rule uses the command: bcc32 -c myprog.c

The implicit rule command tells MAKE to compile MYPROG.C (the macro $< replaces the name myprog.obj with myprog.c).


Command syntax

Commands immediately follow an explicit or implicit rule and must begin on a new line with a space or tab.

Commands can be any operating system command, but they can also include MAKE macros, directives, and special operators that your operating system won’t recognize (however, note that | can't be used in commands). Here are some sample commands:

cd..

bcc32 -c mysource.c

COPY *.OBJ C:\PROJECTA

bcc32 -c $(SOURCE)     #Macros in Using MAKE macros

Commands follow this general syntax:

[prefix...] commands

Command prefixes

Commands in both implicit and explicit rules can have prefixes that modify how MAKE treats the commands. The following table lists the prefixes you can use in makefiles:

Prefix	Description

@	Don't display the command while it's being executed.

-num	Stop processing commands in the makefile when the exit code returned from command exceeds the integer num. Normally, MAKE aborts if the exit code is nonzero. No space is allowed between - and num.

-	Continue processing commands in the makefile, regardless of the exit codes they return.

&	Expand either the macro $**, which represents all dependent files, or the macro $?, which represents all dependent files stamped later than the target. Execute the command once for each dependent file in the expanded macro.

!	Will behave like the & prefix.

Using @

The following command uses the @ prefix, which prevents MAKE from displaying the command onscreen.

diff.exe : diff.obj

    @bcc32 diff.obj

Using -num and -

The -num and - prefixes control the makefile processing when errors occur. You can choose to continue with the MAKE process if an error occurs or you can specify a number of errors to tolerate.

In the following example, MAKE continues processing if BCC32 returns errors:

target.exe : target.obj

target.obj : target.cpp

    -bcc32 -c target.cpp

Using &

The & prefix issues a command once for each dependent file. It is especially useful for commands that don't take a list of files as parameters. For example,

copyall : file1.cpp file2.cpp

    &copy $** c:\temp

invokes COPY twice as follows:

copy file1.cpp c:\temp

copy file2.cpp c:\temp

Without the & modifier, MAKE would call COPY only once. Note: the & prefix only works with $** and $! macros.


MAKE command operators

While you can use any operating system command in a MAKE command section, you can also use the following special operators:

Operator	Description

<	Use input from a specified file rather than from standard input

>	Send the output from command to file

>>	Append the output from command to file

<<	Create a temporary inline file and use its contents as standard input to command. Also, create temporary response file when -N is used. Note: this is only for use with NMAKE.

&&	Create a temporary response file and insert its name in the makefile

delimiter	Use delimiters with temporary response files. You can use any character other than # as a delimiter. Use << and && as a starting and ending delimiter for a temporary file. Any characters on the same line and immediately following the starting delimiter are ignored. The closing delimiter must be written on a line by itself.


Using MAKE macros

A macro is a variable that MAKE expands into a string whenever MAKE encounters the macro in a makefile. For example, you can define a macro called LIBNAME that represents the string "mylib.lib." To do this, type the line LIBNAME = mylib.lib at the beginning of your makefile. Then, when MAKE encounters the macro $(LIBNAME), it substitutes the string mylib.lib. Macros let you create template makefiles that you can change to suit different projects.

To use a macro in a makefile, type $(MacroName) where MacroName is a defined macro. You can use braces or parentheses to enclose MacroName.

MAKE expands macros at various times depending on where they appear in the makefile:

Nested macros are expanded when the outer macro is invoked.

Macros in rules and directives are expanded when MAKE first looks at the makefile.

Macros in commands are expanded when the command is executed.

If MAKE finds an undefined macro in a makefile, it looks for an operating system environment variable of that name (usually defined with SET) and uses its definition as the expansion text. For example, if you wrote $(PATH) in a makefile and never defined PATH, MAKE would use the text you defined for PATH in your AUTOEXEC.BAT. See your operating system manuals for information on defining environment variables.


Defining MAKE macros

The general syntax for defining a macro in a makefile is:

MacroName = expansion_text.

MacroName

is case-sensitive (MACRO1 is different from Macro1).

MacroName

is limited to 512 characters.

expansion_text

is limited to 4096 characters. Expansion characters may be alphanumeric, punctuation, or spaces.

You must define each macro on a separate line in your makefile and each macro definition must start on the first character of the line. For readability, macro definitions are usually put at the top of the makefile. If MAKE finds more than one definition of MacroName, the new definition overwrites the old one.

You can also define macros using the -D command-line option. No spaces are allowed before or after the equal sign (=); however, you can define more than one macro by separating the definitions with spaces. The following examples show macros defined at the command line:

make -Dsourcedir=c:\projecta

make -Dcommand="bcc32 -c"

make -Dcommand=bcc32 option=-c

Macros defined in makefiles overwrite those defined on the command line.


String substitutions in MAKE macros

MAKE lets you temporarily substitute characters in a previously defined macro. For example, if you define the macro

SOURCE = f1.cpp f2.cpp f3.cpp

you can substitute the characters .obj for the characters .cpp by using the MAKE command $(SOURCE:.cpp=.obj). This substitution does not redefine the macro.

Rules for macro substitution:

Syntax: $(MacroName:original_text=new_text)

No space before or after the colon

Characters in original_text must exactly match the characters in the macro definition (text is case-sensitive)

MAKE also lets you use macros within substitution macros. For example,

MYEXT=.C

SOURCE=f1.cpp f2.cpp f3.cpp

$(SOURCE:.cpp=$(MYEXT))      #Changes 'f1.cpp' to 'f1.C', etc.

The caret (^) symbol causes MAKE to interpret the next character literally. This is useful for inserting a new-line character. For example,

MYEXT=.C

SOURCE=f1.cpp f2.cpp f3.cpp

($(SOURCE):.cpp=$(MYEXT)^

)                          # changes 'f1.cpp f2.cpp f3.cpp' to:

                           #  f1.C

                           #  f2.C

                           #  f3.C

Here, the caret tells MAKE to change each occurrence of .cpp to .C followed by the new-line character.

You can use this to create explicit rules that generate response files for TLIB.EXE. For example,

myfile.lib: file1.obj file2.obj file3.obj

    TLIB $@ @&&!

+-$(**: = &^

+-)

!

Here, MAKE substitutes all space characters in the dependency list with a space followed by an ampersand (&) followed by the new-line character followed by "+-". The resulting response file looks like this:

+-file1.obj &

+-file2.obj &

+-file3.obj &

+-


Default MAKE macros

MAKE contains several default macros you can use in your makefiles. The following table lists the macro definition and what it expands to in explicit and implicit rules.

Macro	Expands in implicit	Expands in explicit

$*	path\dependent file	path\target file

$<	path\dependent file+ext	path\target file+ext

$:	path for dependents	path for target

$.	dependent file+ext	target file + ext

$&	dependent file	target file

$@	path\target file+ext	path\target file+ext

$**	path\dependent file+ext	all dependents file+ext

$?	path\dependent file+ext	old dependents

Macro	Expands to	Comment

_ _MSDOS_ _	1	If running under DOS

_ _MAKE_ _	0x0370	MAKE's hex version number

MAKE	make	MAKE's executable file name

MAKEFLAGS	options	The options typed on the command line

MAKEDIR	directory	Directory where MAKE.EXE is located


Modifying default MAKE macros

If the default macros don't give you the exact string you want, macro modifiers let you extract parts of the string to suit your purpose. Macro modifiers are usually used with $< or $@.

To modify a default macro, use this syntax:

$(MacroName [modifier])

The following table lists macro modifiers and provides examples of their use.

Modifier	Part of file name expanded	Example	Result

D	Drive and directory	$(<D)	C:\PROJECTA\

F	Base and extension	$(<F)	MYSOURCE.C

B	Base only	$(<B)	MYSOURCE

R	Drive, directory, and base	$(<R)	C:\PROJA\SOURCE


Using MAKE directives

MAKE directives resemble directives in languages such as C and Pascal. In MAKE, they perform various control functions, such as displaying commands onscreen before executing them. MAKE directives begin either with an exclamation point or a period, and they override any options given on the command line. Directives that begin with an exclamation point must appear at the start of a new line.

The following table lists the MAKE directives and their corresponding command-line options:

Directive	Option	Description

.autodepend	-a	Turns on autodependency checking

.cacheautodepend	-c	Turns on autodependency caching

!cmdswitches	Uses + or - followed by non-string option letters to turn each option on or off. Spaces or tabs must appear before the + or - operator, none can appear between the operator and the option letters.

!elif	Acts like a C else if

!else	Acts like a C else

!endif	Ends an !if, !ifdef, or !ifndef statement

!error	Stops MAKE and prints an error message

!if	Begins a conditional statement

!ifdef	Acts like a C #ifdef, testing whether a given macro has been defined

!ifndef	Acts like a C #ifndef, testing whether a given macro is undefined

.ignore	-i	MAKE ignores the return value of a command

!include	Acts like a C #include, specifying a file to include in the makefile

.keep	-K	Keeps temporary files that MAKE creates (MAKE usually deletes them)

!message	Prints a message to stdout while MAKE runs the makefile

.noautodepend	-a-	Turns off autodependency checking

.nocacheautodepend	-c-	Turns off autodependency caching

.noIgnore	-i-	Turns off .Ignore

.nokeep	-K-	Does not keep temporary files that MAKE creates

.nosilent	-s-	Displays commands before MAKE executes them

.noswap	-S-	Tells MAKE not to swap itself out of memory before executing a command

.path.ext	Tells MAKE to search for files with the extension .ext in path directories

.precious	Saves the target or targets even if the build fails

.silent	-s	MAKE executes commands without printing them first

.suffixes	Determines the implicit rule for ambiguous dependencies

.swap	-S	Tells MAKE to swap itself out of memory before executing a command

!undef	Clears the definition of a macro. After this, the macro is undefined


.autodepend

Autodependencies are the files that are automatically included in the targets you build, such as the header files included in your C++ source code. With .autodepend on, MAKE compares the dates and times of all the files used to build the .OBJ, including the autodependency files. If the dates or times of the files used to build the .OBJ are newer than the date/time stamp of the .OBJ file, the .OBJ file is recompiled. You can use .autodepend (or -a) in place of forming linked dependencies.


!error

The syntax of the !error directive is:

!error message

MAKE stops processing and prints the following string when it encounters this directive:

Fatal makefile exit code: Error directive: message

Embed !error in conditional statements to abort processing and print an error message, as shown in the following example:

!if !$d(MYMACRO)

#if MYMACRO isn't defined

!error MYMACRO isn't defined

!endif

If MYMACRO isn't defined, MAKE terminates and prints:

Fatal makefile 4: Error directive: MYMACRO isn't defined

Error-checking controls

MAKE offers four different controls to control error checking:

The .ignore directive turns off error checking for a selected portion of the makefile.

The -i command-line option turns off error checking for the entire makefile.

The -num prefix, which is entered as part of a rule, turns off error checking for the related command if the exit code exceeds the specified number.

The - prefix turns off error checking for the related command regardless of the exit code.


!if and other conditional directives

The !if directive works like C if statements. As shown here, the syntax of !if and the other conditional directives resembles compiler conditionals:

!if condition	!if condition	!if condition	!ifdef macro
!endif	!else	!elif condition	!endif
	!endif	!endif
The following expressions are equivalent:

!ifdef macro and !if $d(macro)

ifndef macro and !if !$d(macro)

These rules apply to conditional directives:

One !else directive is allowed between !if, !ifdef, or !ifndef and !endif directives.

Multiple !elif directives are allowed between !if, !ifdef, or !ifndef, !else and !endif.

You can't split rules across conditional directives.

You can nest conditional directives.

!if, !ifdef, and !ifndef must have matching !endif directives within the same file.

The following information can be included between !if and !endif directives:

Macro definition  Explicit rule  Implicit rule	!include directive  !error directive  !undef directive
In an if statement, a conditional expression consists of decimal, octal, or hexadecimal constants and the operators shown in the following table.

Operator	Description	Operator	Description

-	Negation	?:	Conditional expression

~	Bit complement	!	Logical NOT

+	Addition	>>	Right shift

-	Subtraction	<<	Left shift

*	Multiplication	&	Bitwise AND

/	Division	|	Bitwise OR

%	Remainder	^	Bitwise XOR

&&	Logical AND	>=	Greater than or equal*

||	Logical OR	<=	Less than or equal*

>	Greater than	==	Equality*

<	Less than	!=	Inequality*

*Operator also works with string expressions.

MAKE evaluates a conditional expression as either a 32-bit signed integer or a character string.


!include

This directive is like the #include preprocessor directive for the C or C++ language-it lets you include the text of another file in the makefile:

!include filename

You can enclose filename in quotation marks (" ") or angle brackets (< >) and nest directives to unlimited depth, but writing duplicate !include directives in a makefile isn't permitted-you'll get the error message cycle in the include file.

Rules, commands, or directives must be complete within a single source file; you can't start a command in an !include file, then finish it in the makefile.

MAKE searches for !include files in the current directory unless you've specified another directory with the -I command-line option.


!message

The !message directive lets you send messages to the screen from a makefile. You can use these messages to help debug a makefile that isn't working properly. For example, if you're having trouble with a macro definition, you could put this line in your makefile:

!message The macro is defined here as: $(MacroName)

When MAKE interprets this line, it will print onscreen (assuming the macro expands to .CPP):

 The macro is defined here as: .CPP


.path.ext

The .path.ext directive tells MAKE where to look for files with a certain extension. The following example tells MAKE to look for files with the .c extension in C:\SOURCE or C:\CFILES and to look for files with the .obj extension in C:\OBJS.

.path.c = C:\CSOURCE;C:\CFILES

.path.obj = C:\OBJS


.precious

If a MAKE build fails, MAKE deletes the target file. The .precious directive prevents the file deletion, which you might desire for certain kinds of targets. For example, if your build fails to add a module to a library, you might not want the library to be deleted.

The syntax for .precious is

.precious: target [target ...]


.suffixes

The .suffixes directive tells MAKE the order (by file extensions) for building implicit rules.

The syntax of .suffixes is

.suffixes: .ext [.ext ...]

where .ext represents the dependent file extensions you list in your implicit rules. For example, you could include the line .suffixes: .asm .c .cpp to tell MAKE to interpret implicit rules beginning with the ones dependent on .ASM files, then .C files, then .CPP files, regardless of what order they appear in the makefile.

The following .suffixes example tells MAKE to look for a source file first with an .ASM extension, next with a .C extension, and finally with a .CPP extension. If MAKE finds MYPROG.ASM, it builds MYPROG.OBJ from the assembler file by calling TASM. MAKE then calls ILINK32; otherwise, MAKE searches for MYPROG.C to build the .OBJ file or it searches for MYPROG.CPP.

.suffixes: .asm .c .cpp

myprog.exe: myprog.obj

    bcc32 myprog.obj

.cpp.obj:

    bcc32 -P -c $<

.asm.obj:

    tasm /mx $<

.c.obj:

    bcc32 -P- -c $<


!undef

!undef (undefine) clears the given macro, causing an !ifdef MacroName test to fail.

The syntax of the !undef directive is

!undef MacroName


Using macros in directives

You can use the $d macro with the !if conditional directive to perform some processing if a specific macro is defined. Follow the $d with macro name enclosed in parentheses or braces, as shown in the following example:

!if $d(DEBUG)                #If DEBUG is defined,

bcc32 -v f1.cpp f2.cpp       #compile with debug information;

!else                        #otherwise

bcc32 -v- f1.cpp f2.cpp      #don't include debug information.

!endif


Null macros

While an undefined macro name causes an !ifdef MacroName test to return false, MacroName defined as null will return true. You define a null macro by following the equal sign in the macro definition with either spaces or a return character. For example, the following line defines a null macro in a makefile:

NULLMACRO =

Either of the following lines can define a null macro on the MAKE command line:

NULLMACRO=""

-DNULLMACRO


Using BPR2MAK.EXE

The BPR2MAK.EXE utility converts XML .BPR project option files to makefile format for use with the command line tools and is automatically invoked from the IDE when using the Project|Export Makefile menu option.

Commandline usage

BPR2Mak [[-t<templatefile>] [-o<outputfile> <projectname><.BPR | .BPK>] [options]

BPR2MAK basics

BPR2Mak.EXE uses one of two template files to generate the makefile depending on the target type.

DEFAULT.BMK

DEFLIB.BMK

DEFLIB.BMK is used for static library targets and DEFAULT.BMK is used for all other target types (DLL, EXE, Etc).

When invoked from the IDE the correct default file will always be used. However from the commandline, if the target type is a static library you must specify the DEFLIB.BMK file is the file to be used.

bpr2mak.exe -t"D:\Program Files\Borland\CBuilder5\Bin\deflib.bmk" SomeLib.bpr

If you do not specify that the DEFLIB.BMK is the template to be used, a "bad" makefile is produced (no errors or warnings, just a makefile that fails to generate the LIB).

Note: By adding projects to a Project Group you will automatically get a correct invocation of Bpr2mak.exe in the .BPG makefile. If you add the project to a group, then all you have to do is make the .BPG and BPR2MAK.EXE automatically gets invoked.

     make -f  myprojects.BPG

Command line options

-t<templatefile>	Name of the file to use as the template (Default = DEFAULT.BMK)
-o<outputfile>	Name of the output file (Default = <projectName>.MAK)
-s	Write output file to stdout instead of a file
-q	Suppress display of progress messages
-h	Dispy the help screen


Using command-line resource tools (overview)
Using command-line resource tools

There are several Borland command-line resource tools:

Resource compiler

BRCC32.EXE is the Borland resource compiler. It compiles resource script files (.RC files) and produces the binary .RES file.

Resource linkers

RLINK32.DLL is the Borland resource linker that binds resources, in .RES file form, to an .EXE file, and marks the resulting .EXE file as a Windows executable. RLINK32.DLL is accessed through ILINK32.EXE.

Resource shells

BRC32.EXE is a shell through which BRCC32 and RLINK32 (through ILINK32) can be started in a single step.


Resource compiler (BRCC32)

See also	Examples

BRCC32 is the command-line version of the resource compiler. It accepts a resource script file (.RC) as input and produces a resource object file (.RES) as output.

Syntax

BRCC32 [options] <filename>.RC

Command-line options

BRCC32 accepts these options:

Option	Description

@responsefile	Takes instructions from the specified command file.

-c <code page>	Uses the specified code page for resource translation. If -c is not used, the default ANSI code page is used.

-d<name>[=<string>]	Defines a preprocessor symbol.

-fo<filename>	Renames the output .RES file. (By default, BRCC32 creates the output .RES file with the same name as the input .RC file.)

-i<path>	Adds one or more directories (separated by semicolons) to the include search path.

-l<language>	Specifies default language.

-m	Indicates that the code page specified with the -c switch contains double-byte character set (DBCS) characters.

-r	This switch is ignored. It is included for compatibility with other resource compilers.

-v	Prints progress messages (verbose).

-x	Deletes the current include path.

-? or -h	Displays help.

-16	Builds a 16-bit resource.

-32	Builds a 32-bit resource.

BRCC32 predefines common resource-related Windows constants such as WS_VISIBLE and BS_PUSHBUTTON. Also, two special compiler-related symbols are defined: RC_INVOKED and WORKSHOP_INVOKED. These symbols can be used in the source text in conjunction with conditional preprocessor statements to control compilation. For example, the following construct can greatly speed up compilation:

#ifndef WORKSHOP_INVOKED

#include "windows.h"

#endif

Downward compatibility

The following syntax and options are supported for downward compatibility:

Syntax

BRCC32 [options] <filename>.RC

Command-line options

BRCC32 accepts these options:

Option	Description

-31	Builds Windows 3.1-compatible .RES files.

-w32	Builds Win32-compatible .RES files.


Resource compiler examples

See also

The following example adds two directories to the include path and produces a .RES file with the same name as the input .RC file.

brcc32 -i<dir1>;<dir2> <filename>.RC

This example produces an output .RES file with a name different from the input .RC file name:

brcc32 -fo<filename>.RES <filename>.RC

This example builds a 16-bit .RES file:

brcc32 -16 -fo<filename>.RES <filename>.RC


Resource linker (RLINK32)
Resource linker (RLINK32.DLL)

See also

RLINK32 combines a .RES file with an .EXE file to produce a new Windows executable. RLINK32 accepts as input one or more object (.RES) files and a single Windows executable file. RLINK32 links the resources by fixing up string tables and message tables and then binding these linked resources into the executable. RLINK32 is called by ILINK32 and is used for 32-bit resources.


Resource shells (BRC32)
Resource shell (BRC32)

See also	Examples

The Borland resource compiler (BRC32) is a resource compiler shell. It invokes BRCC32 and RLINK32, depending on the command-line syntax.

Syntax

brc32 [options] <filename>.RC [<filename>.EXE]

Command-line options

BRC32 accepts these options:

Switch	Description

-d<name>[=string]	Defines a symbol you can test with the #IFDEF preprocessor directive.

-fo<filename>	Renames the .RES file.

-fe<filename>	Renames the .EXE file.

-i<path>	Adds one or more directories (separated by semicolons) to the include search path.

-r	Creates a .RES file only. The compiled .RES file is not added to the .EXE.

-v	Prints progress messages (verbose listing).

-x	Directs the compiler to ignore the INCLUDE environment variable when it searches for include or resource files.

-16	Builds 16-bit .RES files.

-32	Builds 32-bit .RES files.

-Vd.d	Makes the .EXE file with Windows version provided (v3.1 is the default for 16-bit resources; -v4.0 is the default for 32-bit resources). Version options are listed in the following table.

Option	Bit	Resulting look

3.1	16	Gives white background with a non 3-D look for Windows 3.1x, Windows 32s, or WinNT 3.1

4.0	16	Gives gray 3-D look for Windows 95 and WinNT 3.51

3.1	32	Gives white background with a non 3-D look for Windows 32s or WinNT 3.1

4.0	32	Gives gray 3-D look for Windows 95 and WinNT 3.51

The following switches are invalid when the -r switch is specified:

-k	Disables the contiguous preload of segments and resources in the .EXE file. Segments are kept in the order in which they appear in the .DEF file. (This option only applies to 16-bit resources.)

-t	Creates an application that runs only in protected mode (Windows Standard or 386 Enhanced mode).

Downward compatibility

The following syntax and options are supported for downward compatibility

Syntax

brc32 [switches] <filename>.RC [<filename>.EXE]

Command-line options

BRC32 accepts these options:

Option	Description

-31	Builds Windows 3.1-compatible .RES files.

-w32	Builds Win32-compatible .RES files.


Resource shell examples

See also

The following statement compiles the .RC file, creates a .RES file, and adds the .RES file to the executable file:

brc32 <filename>.RC [<filename>.EXE]

BRC32 automatically seeks an .EXE file with the same name as the .RC file. You need to specify the .EXE file only if its name is different from that of the .RC file.

The following statement creates a .RES file, but not an .EXE file. If you name an .EXE file in the command line, BRC ignores it:

brc32 -r <filename>.RC

The following statement adds an existing .RES file to an executable file. The .EXE file name is required only if it differs from the .RES file name:

brc32 <filename>.RES [<filename>.EXE]

This example uses BRC32 to build a 16-bit Windows 3.1 compatible .RES file:

brc32 -16 -v3.1 -fo<filename>.RES <filename>.RC


TDUMP: The file dumping utility

TDUMP.EXE produces a file dump that shows the structure of a file.

TDUMP breaks apart a file structurally and uses the file's extension to determine the output display format. TDUMP recognizes many file formats, including .EXE, .OBJ, and .LIB files. If TDUMP doesn't recognize an extension, it produces a hexadecimal dump of the file. You can control the output format by using the TDUMP command-line options when you start the program.

TDUMP's ability to peek at a file's inner structure displays not only a file's contents, but also how a file is constructed. Moreover, because TDUMP verifies that a file's structure matches its extension, you can also use TDUMP to test file integrity.

TDUMP syntax

The command-line syntax for TDUMP is:

TDUMP [<options>] <Inputfile> [<Listfile>] [<options>]

<Inputfile> is the file whose structure you want to display (or "dump")

<Listfile> is an optional output file name (you can also use the standard DOS redirection command ">")

<options> stand for any of the TDUMP command-line options

Note: For more information on using TDUMP, refer to the online file TDUMP.TXT.


TDUMP command-line options

You can use several optional switches with TDUMP, all of which start with a hyphen or a forward slash. The following two examples are equivalent:

TDUMP -el -v demo.exe

TDUMP /el /v demo.exe

The -a and -a7 options

TDUMP automatically adjusts its output display according to the file type. You can force a file to be displayed as ASCII by including the -a or -a7 option.

  -a  produces an ASCII file display, which shows the offset and the contents in displayable ASCII characters. A character that is not displayable (like a control character) appears as a period.

  -a7 converts high-ASCII characters to their low-ASCII equivalents. This is useful if the file you are dumping sets high-ASCII characters as flags (WordStar files do this).

The -b# option

The -b# option allows you to display information beginning at a specified offset. For example, if you wanted a dump of MYFILE starting from offset 100, you would use:

TDUMP -b100 MYFILE

The -C option

The -C option causes TDUMP to dump information found in COFF format files (.OBJ and .LIB). This option is useful when linking with Microsoft .OBJ and .LIB files.

The -d option

The -d option causes TDUMP to dump any Borland 32-bit debug information found in the .OBJ file. If you do not specify this option, TDUMP displays raw data only.

The -e, -el, -er and -ex options

All four options force TDUMP to display the file as an executable (.EXE) file.

An .EXE file display consists of information contained within a file that is used by the operating system when loading a file. If symbolic debugging information is present (Turbo Debugger or Microsoft CodeView), TDUMP displays it.

TDUMP displays information for DOS executable files, NEW style executable files ( Microsoft Windows and OS/2 .EXEs and DLLs ), Linear Executable files, and Portable Executable (PE) files used by Windows NT and Windows 95/98 and Windows 2000.

-e Display file as Executable (EXE/DLL, DOS, Win16, OS/2, PE)

-ea[:v] Display All Exports unsorted, or (:v) sort by RVA (default dumps only named exports, sorting on the name)

-ed Disable EXE debug information

-ee[=x] List Exports only from EXE/DLL (optional x lists matches only)

-el suppresses line numbers in the display

-eiID   Include only .EXE table ID (HDR, OBJ, FIX, NAM, ENT)

-em[=x] List Imports only from EXE/DLL (optional x lists matches only)

-em.[x] List Imported modules only from EXE/DLL (optional x search string)

-ep Disable EXE PE header display

-er prevents the relocation table from displaying

-ex prevents the display of New style executable information. This means TDUMP only displays information for the DOS "stub" program

The -h option

The -h option displays the dump file in hexadecimal (hex) format. Hex format consists of a column of offset numbers, 16 columns of hex numbers, and their ASCII equivalents (a period appears where no displayable ASCII character occurs).

If TDUMP doesn't recognize the input file's extension, it displays the file in hex format (unless an option is used to indicate another format).

The -i option

The -i<id> option is used to specify the debug table(s) to use

The -l, -li and -le options

The -l option displays the output file in library (.LIB) file format. A library file is a collection of object files (see the -o option for more on object files). The library file dump displays library-specific information, object files, and records in the object file.

The -li option tells TDUMP to display a short form of "impdef" records when dumping import libraries. You can also specify a search string using the following syntax:

-li=<string>

For example, the command

TDUMP -li=codeptr import32.lib

results in the following output:

Impdef:(ord) KERNEL32.0336=ISBADCODEPTR

This output shows that the function is exported by ordinal, whose ordinal value is 336 (decimal). In addition, the output displays the module and function name.

If you give the command

TDUMP -li=walk import32.lib

TDUMP displays:

Impdef:(name) KERNEL32.????=HEAPWALK

This shows the output of a function exported by name.

The –le option tells TDUMP to display a short form of the “expdef” records when dumping OBJ files. You can also specify a search string using the following syntax:

-le=<string>

The -m option

The -m option leaves C++ names occurring in object files, executable files, and Turbo Debugger symbolic information files in "mangled" format. This option is helpful in determining how the C++ compiler "mangles" a given function name and its arguments.

The -o, -oc, -oi, and -ox options

-o displays the file as an object (.OBJ) file. An object file display contains descriptions of the command records that pass commands and data to the linker, telling it how to create an .EXE file. The display format shows each record and its associated data on a record-by-record basis.

-oc causes TDUMP to perform a cyclic redundancy test (CRC) on each encountered record. The display differs from the -o display only if an erroneous CRC check is encountered (the TDUMP CRC value differs from the record's CRC byte).

-oi<id> includes only specified record types in the object module dump. Replace <id> with the name of the record to be displayed. For instance,

TDUMP -oiPUBDEF MYMODULE.OBJ

produces an object module display for MYMODULE.OBJ that displays only the PUBDEF records.

-ox<id> excludes designated record types from the object module dump. Replace <id> with the record name not to be displayed. For instance,

TDUMP -oxPUBDEF MYMODULE.OBJ

produces an object module display for MYMODULE.OBJ that excludes the PUBDEF records.

The -ox and -oi options are helpful in finding errors that occur during linking. By examining the spelling and case of the EXTDEF symbol and the PUBDEF symbol, you can resolve many linking problems. For instance, if you receive an "unresolved external" message from the linker, use TDUMP -oiEXTDEF to display the external definitions occurring in the module causing the error. Then, use TDUMP -oiPUBDEF on the module containing the public symbol the linker could not match.

Another use for the -oi switch is to check the names and sizes of the segments generated in a particular module. For instance,

TDUMP -oiSEGDEF MYMODULE.OBJ

displays the names, attributes, and sizes of all of the segments in MYMODULE.

Note:	To get a list of record types for -oi and -ox, use the command-line options -oi? and -ox?.

The -r option

The -r option causes TDUMP to display raw data.

The -R option

The -R option causes TDUMP to dump relocation tables from 32-bit PE (Win32) format images. The default is to suppress these dumps.

The –s and –su options

The –s option tells TDUMP to display strings. By default –s displays all strings in a given file. You can specify a string, or part of a string, using the following syntax:

-s=<string>

For example, the command

TDUMP -s=black GoGame.exe

results in the following output of all strings containing ‘black’:

56840: IDI_BLACK

81965: Capture Black

85038: black.bmp

The optional string argument is case insensitive. To specify several words of a string, use quotes. For example:

TDUMP -s=”game of go” GoGame.exe

The –su option is used in the same manner, with an optional string argument, and tells TDUMP to display Unix-style strings, meaning with no offset. For example, the command:

TDUMP -su=black GoGame.exe

results in the following output:

IDI_BLACK

Capture Black

black.bmp

For the -s[xx] switch, xx can be:

# - minimum string length to look for (default: 4)

b# - Beginning file offset (-b# is the same as -sb#)

e# - Ending file offset

f - Format (wrap) long strings

s - Search string with case sensitivity (default: no)

u - unix format: no offset (or decimal offsets, -h for hex)

=x - x = search string

The -um option

The -um option is used to display mangled names as unmangled. You do not need to reformat the text to edit out only the mangled names before using this option. You can pass output that has mangled names anywhere in the text, and only the mangled names will be affected.

The -v option

The -v option is used for verbose display. If used with an .OBJ or .LIB file, TDUMP produces a hexadecimal dump of the record's contents without any comments about the records.

If you use TDUMP on a Turbo Debugger symbol table, it displays the information tables in the order in which it encounters them. TDUMP doesn't combine information from several tables to give a more meaningful display on a per-module basis.

The -x option

The -x<id> option is used to specify the debug table(s) to exclude


Using ILINK32

See also

The ILINK32 linker is a command-line tool that combines object modules (.OBJ files), library modules (.LIB files), and resources to produce executables (.EXE, .DLL, and .BPL files). Because the compiler automatically calls the linker, you don't need to call the linker explicitly unless you suppress the linking stage of compilation (see the -c compiler option).

ILINK32 is invoked from the command line and uses a configuration file called ILINK32.CFG, an optional response file, and command-line options.

ILINK32 links 32-bit Windows code and uses the 32-bit resource linker, RLINK32.DLL.


ILINK32, the incremental linker

See also

ILINK32 links object modules (.OBJ files), library modules (.LIB files), and resources to produce executable files (.EXE, .DLL, and .BPL files). ILINK32 creates and maintains a series of state files that contains this information. These state files allow subsequent links to be incremental, greatly reducing the total link time. By default, these file are created in memory, but they can be written to disk.

Linker-state files

The four linker-state files have file names of <Project>.IL?, where <Project> is taken from the name of the project .BPR file, and the character in place of the question mark (?) identifies each of the four individual linker-state files.

Debug-information file

If you include debug information in your final linked executable, ILINK32 will always store the debug information in a separate .TDS file, named <Project Name>.TDS by default. The C++Builder integrated debugger reads this debugger-information file. ILINK32 will always create this file.If you do not have the -v linker switch set, the TDS file is marked as invalid.


ILINK32 command-line syntax

The linker syntax controls how the linkers work. Linker command-line options are case-sensitive.

The linkers can also use a configuration file called ILINK32.CFG for options that you'd normally type at the command-line.

Syntax

ILINK32 [@respfile][options] startup myobjs, [exe], [mapfile], [libraries], [deffile], [resfile]

[@respfile]	A response file is an ASCII file that lists linker options and file names that you would normally type at the command line. By placing options and files names in a response file, you can save the amount of keystrokes you need to type to link your application.

[options]	Linker options that control how the linker works. For example, options specify whether to produce an .EXE or a DLL file. Linker options must be preceded by either a slash (/) or a hyphen (-).

startup	A Borland initialization module for executables or DLLs that arranges the order of the various segments of the program. Failure to link in the correct initialization module usually results in a long list of error messages telling you that certain identifiers are unresolved, or that no stack has been created.

myobjs	The .OBJ files you want linked. Specify the path if the files aren't in the current directory. (The linker appends an .OBJ extensions if no extension is present.)

[exe]	The name you want given to the executable file ( .EXE, or .DLL). If you don't specify an executable file name, ILINK32 derives the name of the executable by appending .EXE or .DLL to the first object file name listed. (The linker assumes or appends an .EXE extensions for executable files if no extension is present. It also assumes or appends a .DLL extension for dynamic link libraries if no extension is present.)

[mapfile]	Is the name you want given to the map file. If you don't specify a name, the map file name is given the same as exefile (but with the .MAP extension). (The linker appends a .MAP extensions if no extension is present.)

[libraries]	The library files you want included at link time. Do not use commas to separate the libraries listed. If a file is not in the current directory or the search path (see the /L option) then you must include the path in the link statement. (The linker appends a .LIB extension if no extension is present.)

The order in which you list the libraries is very important; be sure to use the order defined in this list:

 Code Guard libraries (if needed)

 List any of your own user libraries, noting that if a function is defined more than once, the linker uses the first definition encountered

 IMPORT32.LIB (if you’re creating an executable that uses the Windows API)

 Math libraries

 Runtime libraries

[deffile]	The module definition file for a Windows executable. If you don't specify a module definition (.DEF) file and you have used the /Twe or /Twd option, the linker creates an application based on default settings. (The linker appends a .DEF extension if no extension is present.)

[resfile]	A list of .RES files (compiled resource files) to bind to the executable. (The linker appends an .RES extension if no extension is present.)


ILINK32.CFG File

ILINK32 uses a configuration file called ILINK32.CFG for options that you would normally type at the command line (note that configuration files can contain only options, not file names). Configuration files let you save options you use frequently, so you do not have to continually retype them.

ILINK32 looks for ILINK32.CFG in the current directory, then in the directory from which it was loaded.

The following ILINK32.CFG file tells ILINK32 to look for libraries first in the ..\LIB directory of your Borland compiler, then in C:\WINAPPS\LIB, to include debug information in the executables it creates, to create a detailed segment map, and to produce a Windows executable (.EXE not .DLL).

;Sample ILINK32.CFG file

/Lc:\BORLANDC\LIB;c:\WINAPPS\LIB

/v /s

/Tpe

Note: If you specify command-line options in addition to those recorded in a configuration file, the command-line options override any conflicting configuration options.


Linker response files

You can use response files with the command-line linkers to specify linker options.

Response files are ASCII files that list linker options and file names that you would normally type at the command line. Response files allow you longer command lines than most operating systems support, plus you don't have to continually type the same information. Response files can include the same information as configuration files, but they also support the inclusion of file names.

Unlike the command line, a response file can be several lines long. To specify an added line, end a line with a plus character (+) and continue the command on the next line. Note that if a line ends with an option that uses the plus to turn it on (such as /v+), the + is not treated as a line continuation character (to continue the line, use /v+ +).

If you separate command-line components (such as .OBJ files from .LIB files) by lines in a response file, you must leave out the comma used to separate them on the command line. For example,

/c c0ws+

myprog,myexe +

mymap +

mylib cws

leaves out the commas you'd have to type if you put the information on the command line:

ILINK32 /c c0ws myprog,myexe,mymap,mylib cws

To use response files,

1.	Type the command-line options and file names into an ASCII text file and save the file. Response files shipped with C++Builder have an .RSP extension.

2.	Type ILINK32 @[path]RESFILE.RSP where RESFILE.RSP is the name of your response file.

You can specify more than one response file as follows:

ilink32 /c @listobjs.rsp,myexe,mymap,@listlibs.rsp

Note: You can add comments to response files using semicolons; the linker ignores any text on a line that follows a semicolon.


Using ILINK32 with BCC32.EXE

You can pass options and files to ILINK32 through the command-line compiler (BCC32.EXE) by typing file names on the command line with explicit .OBJ and .LIB extensions. For example,

BCC32 mainfile.obj sub1.obj mylib.lib

links MAINFILE.OBJ, SUB1.OBJ, and MYLIB.LIB to produce the executable MAINFILE.EXE.

Note: By default, BCC32 starts ILINK32 with the files C0W32.OBJ, CW32.LIB, and IMPORT32.LIB (initialization module, run-time library, and Windows import library). In addition, both compilers always pass the linkers the /c (case-sensitive link) option.


Module definition files

Example

The module definition file is an ASCII text file that provides information to ILINK32 about the contents and system requirements of a Windows application. You can create a module definition file using IMPDEF, and you can create import libraries from module definition files using IMPLIB.

With C++Builder, you have the option to use a .DEF file in the project .MAK file.

The module definition file names the .EXE or .DLL, identifies the application type, lists imported and exported functions, describes the code and data segment attributes, and lets you specify attributes for additional code and data segments, specifies the size of the stack, and provides for the inclusion of a stub program.

Specific elements of this module definition file are:

CODE statement

DATA statement

DESCRIPTION statement

EXETYPE statement

EXPORTS statement

HEAPSIZE statement

IMPORTS statement

LIBRARY statement

NAME statement

SECTIONS statement

SEGMENTS statement

STACKSIZE statement

STUB statement

SUBSYSTEM statement

When a module definition file is not specified

If no module definition file is specified, the following defaults are assumed:

CODE	PRELOAD MOVEABLE DISCARDABLE

DATA	PRELOAD MOVEABLE MULTIPLE   ; (for applications)

PRELOAD MOVEABLE SINGLE   ; (for DLLs)

HEAPSIZE	4096

STACKSIZE	1048576

To change an applications attributes from these defaults, you will need to create a module definition file.

If you delete the EXETYPE statement, the C++Builder linker can determine what kind of executable you want to produce from your settings in the IDE or the options you supply on the command line.

You can include an import library to substitute for the IMPORTS section of the module definition.

You can use the __declspec(dllexport) or _export keywords 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 __declspec(dllexport) or _export is used to export a function, that function is exported by name rather than by ordinal. Please also note that __declspec(dllexport) is the preferred method of export


CODE statement (Module Definition File)

See also

CODE defines the default attributes of code segments. Code segments can have any name, but must belong to segment classes whose name ends in CODE (such as CODE or MYCODE). The syntax is:

CODE [PRELOAD | LOADONCALL]

     [EXECUTEONLY | EXECUTEREAD]

PRELOAD means code is loaded when the calling program is loaded.

LOADONCALL (the default) means the code is loaded when called by the program.

EXECUTEONLY means a code segment can only be executed.

EXECUTEREAD (the default) means the code segment can be read and executed.

FIXED (the default) means the segment remains at a fixed memory location.

MOVEABLE means the segment can be moved.

DISCARDABLE means the segment can be discarded if it is no longer needed (this implies MOVEABLE).

NONDISCARDABLE (the default) means the segment can not be discarded.


DATA statement (Module Definition File)

See also

DATA defines attributes of data segments. The syntax is:

DATA [NONE | SINGLE | MULTIPLE]

     [READONLY | READWRITE]

     [PRELOAD | LOADONCALL]

     [SHARED | NONSHARED]

NONE means that there is no data segment created. This option is available only for libraries.

SINGLE (the default for .DLLs) means a single data segment is created and shared by all processes.

MULTIPLE (the default for .EXEs) means that a data segment is created for each process.

READONLY means the data segment can be read only.

READWRITE (the default) means the data segment can be read and written to.

PRELOAD means the data segment is loaded when a module that uses it is first loaded.

LOADONCALL (the default) means the data segment is loaded when it is first accessed. (LOADONCALL is ignored for 32-bit applications.)

SHARED means one copy of the data segment is shared among all processes.

NONSHARED (the default for programs .DLLs) means a copy of the data segment is loaded for each process needing to use the data segment.


DESCRIPTION statement (Module Definition File)

See also

DESCRIPTION (optional) inserts text into the application module and is typically used to embed author, date, or copyright information. The syntax is:

DESCRIPTION 'Text'

Text is an ASCII string delimited with single quotes.


EXETYPE statement (Module Definition File)

See also

EXETYPE defines the default executable file (.EXE) header type for applications. You can leave this section in for 32-bit applications for backward compatibility, but if you need to change the EXETYPE, see the NAME statement. The syntax for EXETYPE is:

EXETYPE  [WINDOWAPI] | [WINDOWCOMPAT]

WINDOWAPI is a Windows executable, and is equivalent to the ILINK32 option /aa.

WINDOWCOMPAT is a Windows-compatible character-mode executable, and is equivalent to the ILINK32 option /ap.


EXPORTS statement (Module Definition File)

See also

EXPORTS defines the names and attributes of 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] [Parameter]

ExportName specifies an ASCII string that defines the symbol to be exported as follows:

EntryName [=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 and is externally visible.

Ordinal defines the function's ordinal value as follows:

@ordinal

where ordinal is an integer value that specifies the function's ordinal value.

When an application or DLL module calls a function exported from a DLL, the calling module can refer to the function by name or by ordinal value. It's faster to refer to the function by ordinal because string comparisons aren't required to locate the function. To use less memory, export a function by ordinal (from the point of view of that function's DLL) and import/call a function by ordinal (from the point of view of the calling module).

When a function is exported by ordinal, the name resides in the nonresident 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 in memory whenever the module is loaded; the nonresident name table isn't.

RESIDENTNAME specifies 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).

Parameter is an optional integer value that specifies the number of words the function expects to be passed as parameters.


HEAPSIZE statement (Module Definition File)

See also

HEAPSIZE defines the number of bytes the application needs for its local heap. An application uses the local heap whenever it allocates local memory.

The syntax for HEAPSIZE is:

HEAPSIZE Reserve[, Commit]

Reserve can be a decimal or hex value, the default of which is 1MB. To help with backward (16-bit) compatibility for 32-bit ports, the linker uses the default value of 1MB if you specify in the .DEF file a reserve value less than 64K.

Commit is a decimal or hex value. The commit size is optional, and if not specified defaults to 4K. The minimum commit size you can specify is 0. In addition, the specified or default commit size must always be smaller or equal to the reserve size.

Reserved memory refers to the maximum amount of memory that can be allocated either in physical memory or in the paging file. In other words, reserved memory specifies the maximum possible heap size. The operating system guarantees that the specified amount of memory will be reserved and, if necessary, allocated.

The meaning of committed memory varies among operating systems. In Windows NT, commited memory refers to the amount of physical memory allocated for the heap at application load/initialization time. Committed memory causes space to be allocated either in physical memory or in the paging file. A higher commit value saves time when the application needs more heap space, but increases memory requirements and possible startup time.

You can override any heap reserve or commit size specified in the .DEF file with the /H or /Hc command-line options. /H lets you specify a heap reserve size less than the 64K minimum allowed in the .DEF file.


IMPORTS statement (Module Definition File)

See also

IMPORTS defines the names and attributes of functions to be imported from DLLs. Instead of listing imported DLL functions in the IMPORTS statement, you can either

specify an import library for the DLL in the ILINK32 command line, or

include the import library for the DLL in the project manager in the IDE.

You must use either __declspec(dllimport) or __import to import any function, class, or data you want imported. The prefered method is to use __declspec(dllimport).

The IMPORTS keyword marks the beginning of the definitions followed by any number of import definitions, each on a separate line. The syntax is:

IMPORTS

[InternalName=]ModuleName.Entry

InternalName is an ASCII string that specifies the unique name the application uses to call the function.

ModuleName specifies one or more uppercase ASCII characters that define the name of the executable module containing the function. The module name must match the name of the executable file. For example, the file SAMPLE.DLL has the module name SAMPLE.

Entry specifies the function to be imported--either an ASCII string that names the function or an integer that gives the function's ordinal value.


LIBRARY statement (Module Definition File)

See also

LIBRARY defines the name of a DLL module. A module definition file can contain either a LIBRARY statement to indicate a .DLL or a NAME statement to indicate a .EXE.

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 [INITGLOBAL | INITINSTANCE]

LibraryName (optional) is an ASCII string that defines the name of the library module. If you don't include a LibraryName, ILINK32 uses the file name with the extension removed. If the module definition file includes neither a NAME nor a LIBRARY statement, ILINK32 assumes a NAME statement without a ModuleName parameter.

INITGLOBAL means the library-initialization routine is called only when the library module is first loaded into memory.

INITINSTANCE means the library-initialization routine is called each time a new process uses the library.


NAME statement (Module Definition File)

See also

NAME is the name of the application's executable module. The module name identifies the module when exporting functions. NAME must appear before EXETYPE. If NAME and EXETYPE don’t specify the same target type, the linker uses the type listed with NAME. The syntax is:

NAME ModuleName [WINDOWSAPI] | [WINDOWCOMPAT]

ModuleName (optional) specifies one or more uppercase ASCII characters that name the executable module. The name must match the name of the executable file. For example, an application with the executable file SAMPLE.EXE has the module name SAMPLE.

If ModuleName is missing, ILINK32 assumes that the module name matches the file name of the executable file. For example, if you do not specify a module name and the executable file is named MYAPP.EXE, ILINK32 assumes that the module name is MYAPP.

If the module definition file includes neither a NAME nor a LIBRARY statement, ILINK32 assumes a NAME statement without a ModuleName parameter.

WINDOWSAPI specifies a Windows executable, and is equivalent to the ILINK32 option /aa.

WINDOWCOMPAT specifies a Windows-compatible character-mode executable, and is equivalent to the ILINK32 option /ap.


SECTIONS statement (Module Definition File)

See also

The SECTIONS statement lets you set attributes for one or more section in the image file. you can use this You can use this statement to override the default attributes for each different type of section. The syntax for SECTIONS is:

SECTIONS

<section_name> [CLASS 'classname'] attributes

SECTIONS marks the beginning of a list of section definitions.

After the SECTIONS keyword, each section definition must be listed on a separate line. Note that the SECTIONS keyword can be on the same line as the first definition or on a preceding line. In addition, the .DEF file can contain one or more SECTIONS statements. The SEGMENTS keyword is supported as a synonym for SECTIONS. The syntax for the individual section listings is as follows:

In this syntax, section_name is case sensitive. The CLASS keyword is supported for compatibility but is ignored. The attributes argument can be one or more of the following: EXECUTE, READ, SHARED, and WRITE.


SEGMENTS statement (Module Definition File)

See also

SEGMENTS defines the segment attributes of additional code and data segments. The syntax is:

SEGMENTS

   SegmentName [CLASS 'ClassName']

   [MinAlloc]

   [SHARED | NONSHARED]

   [PRELOAD | LOADONCALL]

SegmentName is 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 (optional) is the class name of the specified segment. If no class name is specified, ILINK32 uses the class name CODE.

MinAlloc (optional) is an integer that specifies the minimum allocation size for the segment. ILINK32 ignores this value.

SHARED means one copy of the segment is shared among all processes.

NONSHARED (the default for .EXEs and .DLLs) means a copy of the segment is loaded for each process needing to use the data segment.

PRELOAD means that the segment is loaded immediately.

LOADONCALL means that the segment is loaded when it is accessed or called (this is ignored by ILINK32). The Resource Compiler may override the LOADONCALL option and preload segments instead.


STACKSIZE statement (Module Definition File)

See also

STACKSIZE defines the number of bytes the application needs for its local stack. An application uses the local stack whenever it makes function calls.

The syntax for STACKSIZE is:

STACKSIZE Reserve[, Commit]

Reserve can be a decimal or hex value, the default of which is 1MB. To help with backward (16-bit) compatibility, the linker uses the default value of 1MB if you specify in the .DEF file a reserve value less than 64K.

Commit is a decimal or hex value. The commit size is optional, and if not specified defaults to 8K. The minimum commit size you can specify is 4K. In addition, the specified or default commit size must always be smaller or equal to the reserve size.

Reserved memory refers to the maximum amount of memory that can be allocated either in physical memory or in the paging file. In other words, reserved memory specifies the maximum possible stack size. The operating system guarantees that the specified amount of memory will be reserved and, if necessary, allocated.

The meaning of committed memory varies among operating systems. In Windows NT, commited memory refers to the amount of physical memory allocated for the stack at application load/initialization time. Committed memory causes space to be allocated either in physical memory or in the paging file. A higher commit value saves time when the application needs more stack space, but increases memory requirements and possible startup time.

You can override any stack reserve or commit size specified in the .DEF file with the /S or /Sc command-line options. /S lets you specify a stack reserve size less than the 64K minimum allowed in the .DEF file.

Note: Do not use the STACKSIZE statement when compiling .DLLs.


STUB statement (Module Definition File)

See also

STUB appends a DOS executable file specified by FileName to the beginning of the module. The executable stub displays a warning message and terminates if the user attempts to run the executable stub in the wrong environment (running a Windows application under DOS, for example).

C++Builder adds a built-in stub to the beginning of a Windows application unless a different stub is specified with the STUB statement. You should not use the STUB statement to include WINSTUB.EXE because the linker does this automatically.

The syntax is:

STUB 'FileName'

FileName is the name of the DOS executable file to 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, ILINK32 searches for the file in the directories specified by the PATH environment variable.


SUBSYSTEM statement (Module Definition File)

See also

SUBSYSTEM lets you specify the Windows subsystem and subsystem version number for the application being linked. The syntax for SUBSYSTEM is:

SUBSYSTEM [subsystem,]subsystemID

The optional parameter subsystem can be any one of the following values: WINDOWS, WINDOWAPI, WINDOWCOMPAT. If you do not specify a subsystem, the linker defaults to a WINDOWS subsystem.

You must specify the subsystemID parameter using the format d.d where d is a decimal number. For example, if you want to specify Windows 4.0, you could use either one of the following two SUBSYSTEM statements:

SUBSYSTEM 4.0

SUBSYSTEM WINDOWS,4.0

You can override any SUBSYSTEM statement in a .DEF file using the /a and /V command-line options.


Example module definition file

See also

Here's a module definition file to serve as an example.

NAME           WHELLO

DESCRIPTION    'C++ Windows Hello World'

EXETYPE        WINDOWS

CODE           MOVEABLE

DATA           MOVEABLE MULTIPLE

HEAPSIZE       1024

STACKSIZE      5120

EXPORTS        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 LIBRARY instead of NAME. Every module definition file should have either a NAME 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 is WINDOWS. Only WINDOWS is supported in this version of C++Builder.

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 run time. 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.

EXPORTS lists those functions in the WHELLO application that can 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, C++Builder provides the __declspec(dllexport) and __export keywords. Functions flagged with __declspec(dllexport) or __export are identified by the linker and entered into an export table for the module. If the Smart Callbacks option is used at compile time (/WS on the BCC32 command-line, or Options|Compiler|Entry/Exit Code|Windows Smart Callbacks), then callback functions do not need to be listed either in the EXPORTS statement or flagged with the __declspec(dllexport) or __export keyword. C++Builder 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 IMPORT32.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.

This application doesn't include a STUB statement. C++Builder 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.


TRIGRAPH: A Character-Conversion Utility

Trigraphs are three-character sequences that replace certain characters used in the C language that are not available on some keyboards. Translating trigraphs in the compiler would slow compilation down considerably, so Borland C++ provides a filter named TRIGRAPH.EXE to handle trigraph sequences when you need to. The syntax for invoking this program is as follows:

TRIGRAPH [-u] file(s) [...]

The following table shows the trigraph sequences that TRIGRAPH.EXE recognizes:

Trigraph	Characters

??=	#

??(	[

??)	]

??/	\

??'	^

??<	{

??>	}

??!	|

??-	~


Using VCTOBPR.EXE

Overview of MSVC compatibility

The VCTOBPR utility converts Microsoft Visual C++ 5.0 and 6.0 project (.DSP) and workspace (.DSW) files to their equivalent Borland C++Builder files.

You can launch VCTOBPR from the C++Builder Tools menu (Visual C++ Project Conversion Utility command) or from the command line.

Note:  You can’t run VCTOBPR on read-only files, such as those contained on a CD-ROM.  So make sure the files you want to convert are in a read/write state and location.

Syntax

The command-line syntax is

vctobpr [-#] [-i] filename.dsp

-Or-

vctobpr filename.dsw

-Or-

vctobpru [-i]

Parameters

The following table describes the VCTOBPR parameters:

Name	Description

-#	The number of a specific configuration within a project file to convert. To see the list of configurations, specify –0.  The # parameter has no effect on workspace files.

-i	The include path for any associated IDL files.

filename	The name of a Microsoft Visual C++ project or workspace file to convert.

Note:  The vctobpru syntax runs the graphical front-end for VCTOBPR.

Supported Microsoft projects

The VCTOBPR utility can convert any of the following types of Microsoft Visual C++ projects: ATL COM App, MFC ActiveX Control, MFC App (DLL), MFC App (EXE), Win32 App, Win32 Console App, Win32 Dynamic Link Library, Win32 Static Library.

About the generated files

VCTOBPR generates files according to the following guidelines.

If a workspace file is specified, VCTOBPR creates a .BPG file, adding entries that make each project.

If a project file is specified, VCTOBPR creates a .BPR and a .BPF file with the same name as the project file, backing up existing files if necessary. The following entries are added to the .BPF file

USEUNIT("dependent .CPP filename") // one for each linked OBJ file

USELIB("dependent .LIB filename") // one for each LIB file

USETLB("dependent .TLB filename") // one for each TLB file

USE("dependent .XXX filename") // one for each miscellaneous file

USERC("dependent .RC filename")  // one for each RC file

USERES("dependent .RES filename")  // one for each RES file

USEDEF("dependent .DEF filename")  // one for each DEF file

#define WinMain // EXE

-or-

#define DllEntryPoint // DLL

Notes

If an .ODL or .IDL file is part of the project, VCTOBPR runs the MIDL compiler to produce the .TLB or header files.

VCTOBPR issues warnings for Microsoft switches it does not recognize or cannot convert.

VCTOBPR adds _NO_VCL to the list of macro defines.

VCTOBPR prepends MSC_VER=1100 to the list of macro defines for MFC applications.

VCTOBPR adds the VF and g0 compiler switches to MFC applications.

MFC applications cannot be switched from Debug mode to Release mode and vice versa using the buttons on the Compiler tab in the Options dialog. This is because MFC libraries with different names need to be included in the project base on the mode. To switch between Debug and Release modes, run VCTOBPR again, specifying the configuration corresponding to the mode you want.

Fixing compile errors

If you encounter errors when compiling a converted project, you may need to make some changes to the source code. For more information, see Overview of compatibility between C++Builder and Microsoft Visual C++.


VC++ conversion wizard

VCTOBPR overview

Filename box

In the Filename box, specify the name of a Microsoft Visual C++ project (.DSP) or workspace (.DSW) file.  You can enter the filename manually or browse for the file by clicking the Browse button.


VC++ conversion wizard

VCTOBPR overview

Project selection box

In the project selection box, select the project file (.DSP) to convert.  The project selection box shows the project files contained in the Microsoft Visual C++ workspace (.DSW) file you specified previously.


VC++ conversion wizard

VCTOBPR overview

Project configuration box

In the project configuration box, select the project configuration to use in the conversion.  The project selection box shows all configurations defined in the Microsoft Visual C++ project (.DSP) file you specified previously.


VC++ conversion wizard

VCTOBPR overview

Conversion status box

The conversion status box shows the following information:

the names of files being converted and generated.

the name of the project configuration being converted.

any conversion warnings, such as unsupported linker and compiler options.

the names of backup files, which contain the original, unconverted files.


Overview of Microsoft Visual C++ compatibility

C++Builder includes new compiler and runtime library features that make it easier to compile and link Microsoft Visual C++ 5.0 and 6.0 project (.DSP) files, workspace (.DSW), and source files.

C++Builder also includes VCTOBPR, a new Microsoft Visual C++ project conversion utility.  For information about VCTOBPR, see Using VCTOBPR.EXE.

The following topics describe compatibility between C++Builder and Microsoft Visual C++:

Compiler compatibility

Linker compatibility

Runtime library compatibility


Compiler compatibility between C++Builder and Visual C++

Overview of MSVC compatibility

The following sections describe

enhancements to the C++Builder compiler for Microsoft compatibility.

unsupported Microsoft compiler keywords and directives.

workarounds for unsupported compiler keywords and directives.

Compiler enhancements

The C++Builder compiler is more compatible with the Microsoft Visual C++ compiler.

Unsupported Microsoft compiler keywords and directives

The following Microsoft compiler keywords and directives are not supported in C++Builder.

Keyword or Directive	Description

__declspec(allocate)	Specifies a data segment in which the data item will be allocated.

__declspec(noreturn)	Used to prevent warnings, can be removed or defined away.

__declspec(nothrow)	Used for size optimization, can be removed or defined away.

__declspec(property)	This attribute can be applied to non-static "virtual data members" in a class or structure definition. The compiler treats these "virtual data members" as data members by changing their references into function calls.

__declspec(uuid(string))	Attaches a GUID to a class or structure declared or defined (full COM object definitions only) with the uuid attribute.

Implementation differences

The following compiler keywords and directives are implemented differently in C++Builder:

Keyword or Directive	Description

__declspec(fastcall)	MSVC uses a different number and order of registers to pass parameters.

__declspec vs. _declspec	MSVC supports _declspec as an alias for __declspec.

In addition, there are differences in the way floats and structures are returned by value.

Compiling source files containing __fastcall

To compile Microsoft projects containing __fastcall,

1.	Run VCTOBPR.

2.	In the VCTOBPR-generated files, remove the __fastcall keyword or create a wrapper for each __fastcall function so that it can be called from a C++Builder application.  For information about the C++Builder version of __fastcall, see __fastcall in the C++Builder Programmer’s Guide.


Runtime library compatibility between C++Builder and Visual C++

Overview of MSVC compatibility

The following sections describe

unsupported Microsoft runtime library functions and types.

workarounds for unsupported runtime library functions and types.

Unsupported Microsoft runtime library functions and types

The following Microsoft runtime library functions are not supported:

_bstr_t

_commit

_fpieee_flt

_futime()

_getdrives()

_getmbcp

_getsystime()

_set_se_translator

_seterrormode()

_setmbcp

_setsystime()

_variant_t

isleadbyte

Compiling source files containing unsupported runtime library functions and types

To compile source files containing these unsupported functions and types, you must remove them or replace them with equivalent Windows API, C++Builder, or custom functions and types.


Linker compatibility between C++Builder and Visual C++

Overview of MSVC compatibility

Unsupported linker options

The following Microsoft Visual C++ linker options are not supported:

Option	Description

/DRIVER[:UPONLY]

/ENTRY:function	Sets the starting address.

/EXETYPE:DYNAMIC	Builds a virtual device driver.

/FIXED[:NO]

/GPSIZE:#	Specifies the size of communal variables for MIPS and Alpha platforms.

/INCLUDE:symbol	Forces symbol references.

/VXD	Creates a virtual device driver (VxD).

/SWAPRUN:{NET|CD}	Tells the operating system to copy the linker output to a swap file before running it.


Deprecated elements
Deprecated features and elements in C++Builder

The following program features and language elements are either no longer supported or no longer used in this release of C++Builder.

RTL elements

farfree

faralloc

farmalloc

farheapcheck

farrealloc

inp

inpw

outp

outpw

inport

inportb

outport

outportb


farfree_ex

This feature or language element is no longer used or supported in this product.


faralloc_ex

This feature or language element is no longer used or supported in this product.


farmalloc_ex

This feature or language element is no longer used or supported in this product.


farheapcheck_ex

This feature or language element is no longer used or supported in this product.


farrealloc_ex

This feature or language element is no longer used or supported in this product.


inp_ex

This feature or language element is no longer used or supported in this product.


inpw_ex

This feature or language element is no longer used or supported in this product.


outp_ex

This feature or language element is no longer used or supported in this product.


outpw_ex

This feature or language element is no longer used or supported in this product.


inport_ex

This feature or language element is no longer used or supported in this product.


inportb_ex

This feature or language element is no longer used or supported in this product.


outport_ex

This feature or language element is no longer used or supported in this product.


outportb_ex

This feature or language element is no longer used or supported in this product.


Compiler options (alphabetical listing)

See also

The following table is an alphabetical listing of the C++Builder compiler options:

Option	Description

@<filename>	Read compiler options from the response file filename

+<filename>	Use alternate compiler configuration file filename

-3	Generate 80386 protected-mode compatible instructions (Default)

-4	Generate 80386/80486 protected-mode compatible instructions

-5	Generate Pentium instructions

-6	Generate Pentium Pro instructions

-A	Use ANSI keywords and extensions

-AK	Use Kernighan and Ritchie keywords and extensions

-AT	Use Borland C++ keywords and extensions (also -A-)

-AU	Use UNIX V keywords and extensions

-a	Default (-a4) data alignment; -a- is byte alignment (-a1)

-an	Align data on "n" boundaries, where 1=byte, 2=word (2 bytes), 4=double word (4 bytes), 8=quad word (8 bytes), 16=paragraph (16 bytes) (Default: -a4)

-B	Compile to .ASM (-S), then assemble to .OBJ

-b	Make enums always integer-sized (Default: -b makes enums integer size)

-b-	Makes enums byte-sized when possible

-C	Turn nested comments on (Default: -C- turn nested comments off)

-CP	Enable code paging (for MBCS)

-c	Compile to .OBJ, no link

-D<name>	Define "name" to the null string

-D<name=string>	Define "name" to "string"

-d	Merge duplicate strings

-d-	Does not merge duplicate strings (Default)

-E<filename>	Specify assembler

-e<filename>	Specify executable file name

-f	Emulate floating point

-f-	No floating point

-ff	Fast floating point

-fp	Correct Pentium FDIV flaw

-gb	Stop batch compilation after first file with warnings (Default = OFF)

-gn	Warnings: stop after n messages (Default = 255)

-G, -G-	Optimize for size/speed; use – O1 and –O2 instead

-H	Generate and use precompiled headers

-H-	Does not generate or use precompiled headers (Default)

-H=<filename>	Set the name of the file for precompiled headers

-H"xxx"	Stop precompiling after header file xxx

-Hc	Cache precompiled header (Must be used with -H or -H"xxx"

-He	Enable precompiled headers with external type files (Default)

-Hh=xxx	Stop precompiling after header file xxx

-Hs	Enable smart cached precompiled headers (Default)

-Hu	Use but do not generate precompiled headers

-I<path>	Include file search path

-in	Make significant identifier length to be n (Default = 250)

-Ja	Expand all template members (including unused members)

-jb	Stop batch compilation after first file with errors (Default = OFF)

-Jgd	Generate definitions for all template instances and merge duplicates (Default)

-Jgx	Generate external references for all template instances

-jn	Errors: stop after n messages (Default = 25)

-K	Default character type unsigned (Default: -K- default character type signed)

-k	Turn on standard stack frame (Default)

-L<path>	Library file search path

-lx	Pass option x to linker

-l-x	Disables option x for the linker

-M	Create a Map file

-n<path>	Sets output directory to path

-O	Optimize jumps

-O1	Generate smallest possible code

-O2	Generate fastest possible code

-Oc	Eliminate duplicate expressions within basic blocks and functions

-Od	Disable all optimizations

-Oi	Expand common intrinsic functions

-OS	Pentium instruction scheduling

-O-S	Disables instruction scheduling

-Og	Optimize for speed; use –O2 instead

-Os	Optimize for speed; use –O2 instead

-Ot	Optimize for size; use –O1 instead

-Ov	Enable loop induction variable and strength reduction

-Ox	Optimize for speed; use –O2 instead

-o<filename>	Compile .OBJ to filename

-P	Perform C++ compile regardless of source extension

-P-	Perform C++ compile depending on source file extension

-P<ext>	Perform C++ compile, set output to extension to .ext

-p	Use Pascal calling convention

-p-	Use C calling convention

-pc	Use C calling convention (Default: -pc, -p-)

-pm	Functions without an explicit calling convention to use __msfastcall.

-pr	Use fastcall calling convention for passing parameters in registers

-ps	Use stdcall calling convention

-Q	Extended compiler error information(Default = OFF)

-q	Suppress compiler identification banner (Default = OFF)

-R	Include browser information in generated .OBJ files

-RT	Enable runtime type information (Default)

-r	Use register variables (Default)

-r-	Disable the use of register variables

-rd	Use register variables only when register keyword is employed

-S	Compile to assembler

-T-	Removes all assembler options

-Tx	Specify assembler option x

-tW	Target is a Windows application (same as -W)

-tWC	Target is a console application (same as -WC)

-tWD	Generate a .DLL executable (same as -WD)

-tWM	Generate a 32-bit multi-threaded target (same as -WM)

-tWR	Target uses the dynamic RTL (same as -WR)

-tWV	Target uses the VCL

-U<name>	Undefine any previous definitions of name

-u	Generate underscores (Default)

-V	Use smart C++ virtual tables (Default)

-V0	External C++ virtual tables

-V1	Public C++ virtual tables

-VC	Calling convention mangling compatibility

-Vd	for loop variable scoping

-Ve	Zero-length empty base classes

-VM	Microsoft Visual C++ compatibility

-VI-	Use old Borland search algorithm to locate header files (look first in current working directory)

-Vl	Use old-style Borland C++ structure layout (for compatibility with older versions of BCC32.EXE)

-VF	MFC compatibility

-Vmd	Use the smallest possible representation for member pointers

-Vmm	Support multiple inheritance for member pointers

-Vmp	Honor declared precision of member pointers

-Vms	Support single inheritance for member pointers

-Vmv	Place no restrictions on where member pointers can point (Default)

-Vx	Zero-length empty class member functions

-v	Turn on source debugging

-vG	All Codeguard options on

-vGc	Inline pointer access (Codeguard)

-vGd	Global and stack data accesses (Codeguard)

-vGt	this pointer on member function entry (Codeguard)

-vi	Control expansion of inline functions

-W	Target is a Windows application (same as -tW)

-WC	Target is a console application (same as -tWC)

-WD	Generate a .DLL executable (same as -tWD)

-WM	Generate a 32-bit multi-threaded target (same as -tWM)

-WR	Target uses the dynamic RTL (same as -tWR)

-WU	Generates Unicode application

-w	Display warnings on

-w!	Returns non-zero from compiler on warnings

-wxxx	Enable xxx warning message

-w-xxx	Disable xxx warning message

-wmsg	User-defined warnings

-X	Disable compiler autodependency output (Default: -X- use compiler autodependency output)

-x	Enable exception handling (Default)

-xd	Enable destructor cleanup (Default)

-xdg	Use global destructor count (for compatibility with older versions of BCC32.EXE)

-xf	Enable fast exception prologs

-xp	Enable exception location information

-xs	Enable slow exception epilogues

-y	Debug line numbers on

Message options (alphabetical listing)

Option	Number (Alias)	Warning Message

-w-ali	-w-8086	Incorrect use of #pragma alias “aliasName” = “substitutename” (Default ON)

-wamb	-w8000	Ambiguous operators need parentheses (Default OFF)

-wamp	-w8001	Superfluous & with function (Default OFF)

-w-asc	-w-8002	Restarting compile using assembly (Default ON)

-wasm	-w8003	Unknown assembler instruction (Default OFF)

-w-aus	-w-8004	'identifier' is assigned a value that is never used (Default ON)

-wbbf	-w8005	Bit fields must be signed or unsigned int (Default OFF)

-w-bei	-w-8006	Initializing 'identifier' with 'identifier' (Default ON)

-w-big	-w-8007	Hexadecimal value contains more than three digits (Default ON)

-w-ccc	-w-8008	Condition is always true OR Condition is always false (Default ON)

-wcln	-w8009	Constant is long (Default OFF)

-w-cod	-w-8093	Incorrect use of #pragma codeseg (Default ON)

-w-com	-w-8010	Continuation character \ found in // comment (Default ON)

-w-cpt	-w-8011	Nonportable pointer comparison (Default ON)

-w-csu	-w-8012	Comparing signed and unsigned values (Default ON)

-wdef	-w8013	Possible use of 'identifier' before definition (Default OFF)

-w-dig	-w-8014	Declaration ignored (Default ON)

-w-dpu	-w-8015	Declare 'type' prior to use in prototype (Default ON)

-w-dsz	-w-8016	Array size for 'delete' ignored (Default ON)

-w-dup	-w-8017	Redefinition of 'macro' is not identical (Default ON)

-w-eas	-w-8018	Assigning ‘type’ to ‘enum’  (Default ON)

-w-eff	-w-8019	Code has no effect (Default ON)

-w-ext	-w-8020	'identifier' is declared as both external and static (Default ON)

-w-hch	-w-8021	Handler for 'type1' Hidden by Previous Handler for 'type2' (Default ON)

-w-hid	-w-8022	'function1' hides virtual function 'function2' (Default ON)

-w-ias	-w-8023	Array variable 'identifier' is near (Default ON)

-w-ibc	-w-8024	Base class 'class1' is also a base class of 'class2' (Default ON)

-w-ifr	-w-8085	Function 'function' redefined as non-inline (Default ON)

-w-ill	-w-8025	Ill-formed pragma (Default ON)

-w-inl	-w-8026	Functions containing certain constructs are not expanded inline (Default ON)

-w-inl	-w-8027	Functions containing reserved words are not expanded inline (Default ON)

-w-lin	-w-8028	Temporary used to initialize 'identifier' (Default ON)

-w-lvc	-w-8029	Temporary used for parameter 'parameter' (Default ON)

-w-lvc	-w-8030	Temporary used for parameter 'parameter' in call to 'function' (Default ON)

-w-lvc	-w-8031	Temporary used for parameter number (Default ON)

-w-lvc	-w-8032	Temporary used for parameter number in call to 'function' (Default ON)

-w-mcs	-w-8096	Incorrect use of #pragma code_seg (Default ON)

-w-mes	-w-8095	Incorrect use of #pragma message (Default ON)

-w-mpc	-w-8033	Conversion to ‘type’ fails for members of virtual base ‘base’ (Default ON)

-w-mpd	-w-8034	Maximum precision used for member pointer type ‘type’ (Default ON)

-w-msg	-w-8035	User-defined warnings (Default ON)

-wnak	-w8036	Non-ANSI Keyword Used: 'keyword' (Default OFF)
(Note: Use of this option is required for ANSI conformance)

-w-ncf	-w-8037	Non-const function ‘function’ called for const object (Default ON)

-w-nci	-w-8038	Constant member 'identifier' is not initialized (Default ON)

-w-ncl	-w-8039	Constructor initializer list ignored (Default ON)

-w-nfd	-w-8040	Function body ignored (Default ON)

-w-ngu	-w-8041	Negating unsigned value (Default ON)

-w-nin	-w-8042	Initializer for object 'identifier' ignored (Default ON)

-w-nma	-w-8043	Macro definition ignored (Default ON)

-w-nmu	-w-8044	#undef directive ignored (Default ON)

-wnod	-w8045	No declaration for function 'function' (Default OFF)

-w-nop	-w-8046	Pragma option pop with no matching option push (Default ON)

-w-npp	-w-8083	Pragma pack pop with no matching pack push (Default ON)

-w-nsf	-w-8047	Declaration of static function 'function(...)' ignored (Default ON)

-w-nst	-w-8048	Use qualified name to access nested type 'type' (Default ON)

-w-ntd	-w-8049	Use '> >' for nested templates instead of '>>' (Default ON)

-w-nto	-w-8050	No type OBJ file present. Disabling external types option. (Default ON)

-w-nvf	-w-8051	Non-volatile function ‘function’ called for volatile object (Default ON)

-w-obi	-w-8052	Base initialization without a class name is now obsolete (Default ON)

-w-obs	-w-8053	'identifier' is obsolete (Default ON)

-w-ofp	-w-8054	Style of function definition is now obsolete (Default ON)

-w-onr	-w-8097	Not all options can be restored at this time (Default ON)

-w-osh	-w-8055	Possible overflow in shift operation (Default ON)

-w-ovf	-w-8056	Integer arithmetic overflow (Default ON)

-w-par	-w-8057	Parameter 'parameter' is never used (Default ON)

-w-pch	-w-8058	Cannot create pre-compiled header: ‘header’ (Default ON)

-w-pck	-w-8059	Structure packing size has changed (Default ON)

-w-pcm	-w-8094	Incorrect use of #pragma comment (Default ON)

-w-pia	-w-8060	Possibly incorrect assignment (Default ON)

-wpin	-w8061	Initialization is only partially bracketed (Default OFF)

-w-pow	-w-8062	Previous options and warnings not restored (Default ON)

-w-prc	-w-8084	Suggest parentheses to clarify precedence (Default OFF)

-w-pre	-w-8063	Overloaded prefix operator 'operator' used as a postfix operator (Default ON)

-w-pro	-w-8064	Call to function 'function' with no prototype (Default ON)

-w-pro	-w-8065	Call to function 'function' with no prototype (Default ON)

-w-rch	-w-8066	Unreachable code (Default ON)

-w-ret	-w-8067	Both return and return of a value used (Default ON)

-w-rng	-w-8068	Constant out of range in comparison (Default ON)

-w-rpt	-w-8069	Nonportable pointer conversion (Default ON)

-w-rvl	-w-8070	Function should return a value (Default ON)

-wsig	-w8071	Conversion may lose significant digits (Default OFF)

-w-spa	-w-8072	Suspicious pointer arithmetic (Default ON)

-w-stl	-w-8087	‘operator==’ must be publicly visible to be contained by a ‘name’ (Default OFF)

-w-stl	-w-8089	‘operator<’ must be publicly visible to be contained by a ‘name’ (Default OFF)

-w-stl	-w-8090	‘operator<’ must be publicly visible to be used by a ‘name’ (Default OFF)

-w-stl	-w-8091	‘type’ argument ‘argument’ passed to ‘function’ is a ‘type’ iterator. ‘type’ iterator required (Default OFF)

-w-stl	-w-8092	‘type’ argument ‘argument’ passed to ‘function’ is not an iterator. ‘type’ iterator required (Default OFF)

-wstu	-w8073	Undefined structure 'structure' (Default OFF)

-wstv	-w8074	Structure passed by value (Default OFF)

-w-sus	-w-8075	Suspicious pointer conversion (Default ON)

-w-tai	-w-8076	Template instance 'instance' is already instantiated (Default ON)

-w-tes	-w-8077	Explicitly specializing an explicitly specialized class member makes no sense (Default ON)

-w-thr	-w-8078	Throw expression violates exception specification (Default ON)

-wucp	-w8079	Mixing pointers to different 'char' types (Default OFF)

-wuse	-w8080	'identifier' declared but never used (Default OFF)

-w-voi	-w-8081	void functions may not return a value (Default ON)

-w-zdi	-w-8082	Division by zero (Default ON)


Compiler options (functional listing)

See also

Compiler options are grouped into the following functional categories:

Compiler-specific options

Configuration and Response files

Defines

Code generation

Floating point

Compiler output

Source

Debugging

Precompiled headers

Processor

Calling convention

C++-specific options

C++ compatibility

Virtual tables

Templates

Exception handling

Optimization options

Codeguard options

Warning message options

Portability

ANSI violations

Obsolete C++

Potential C++ errors

Inefficient C++ coding

Potential errors

Inefficient coding

General

Linker options

General options

Map file options

Path options

Image control options

Compiler configuration files

@<filename>	Read compiler options from the response file " filename

Compiler response files

+<filename>	Use alternate configuration file filename

Compiler options | Defines

-D<name>	Define name to the null string

-Dname=string	Define "name" to "string"

-U<name>	Undefine any previous definitions of name

Compiler options | Code generation

-an	Align data on "n" boundaries, where 1=byte, 2=word (2 bytes), 4=Double word (4 bytes), 8=Quad word (8 bytes), 16=Paragraph (16 bytes) (Default: -a4)

-b	Make enums always integer-sized (Default: -b makes enums integer size)

-CP	Enable code paging (for MBCS)

-d	Merge duplicate strings

-K	Default character type unsigned (Default: -K- default character type signed)

-r	Use register variables (Default)

-rd	Use register variables only when register keyword is employed

-WU	Generates Unicode application

Compiler options | Floating point

-f-	No floating point

-f	Emulate floating point

-ff	Fast floating point

-fp	Correct Pentium fdiv flaw

Compiler options | Compiler output

-c	Compile to .OBJ, no link

-e<filename>	Specify executable file name

-lx	Pass option x to linker

-M	Create a Map file

-o<filename>	Compile .OBJ to filename

-P	Perform C++ compile regardless of source extension

-P<ext>	Perform C++ compile, set output to extension to .ext

-Q	Extended compiler error information(Default = OFF)

-tW	Target is a Windows application

-tWC	Target is a console application

-tWD	Generate a .DLL executable

-tWM	Generate a 32-bit multi-threaded target

-tWR	Target uses the dynamic RTL

-tWV	Target uses the VCL

-X	Disable compiler autodependency output (Default: -X- use compiler autodependency output)

-u	Generate underscores (Default)

Compiler options | Source

-C	Turn nested comments on (Default: -C- turn nested comments off)

-in	Make significant identifier length to be "n" (Default = 250)

-AT	Use Borland C++ keywords (also -A-)

-A	Use only ANSI keywords

-AU	Use only UNIX V keywords

-AK	Use only Kernighan and Ritchie keywords

-VF	MFC compatibility

-VI-	Use old Borland search algorithm to locate header files (look first in current working directory)

Compiler options | Debugging

-k	Turn on standard stack frame (Default)

-vi	Control expansion of inline functions

-y	Line numbers on

-v	Turn on source debugging

-R	Include browser information in generated .OBJ files

Compiler options | Precompiled headers

-H	Generate and use precompiled headers (Default)

-Hu	Use but do not generate precompiled headers

-Hc	Cache precompiled header

-He	Enable precompiled headers with external type files (Default)

-Hs	Enable smart cached precompiled headers (Default)

-H=filename	Set the name of the file for precompiled headers

-H\"xxx\"	Stop precompiling after header file xxxx

-Hh=xxx	Stop precompiling after header file xxx

Compiler options | Processor

-3	Generate 80386 instructions. (Default)

-4	Generate 80486 instructions

-5	Generate Pentium instructions

-6	Generate Pentium Pro instructions

Compiler options | Calling convention

-p	Use Pascal calling convention

-pc	Use C calling convention (Default: -pc, -p-)

-pr	Use fastcall calling convention for passing parameters in registers

-ps	Use stdcall calling convention

Compiler options | Assembler-code options

-B	Compile to .ASM (-S), then assemble to .OBJ

-E<filename>	Specify assembler

-S	Compile to assembler

-Tx	Specify assembler option x

C++ options | C++ compatibility

-VC	Calling convention mangling compatibility

-Vd	for loop variable scoping

-Ve	Zero-length empty base classes

-Vl	Use old-style Borland C++ structure layout (for compatibility with older versions of BCC32.EXE)

-Vmd	Use the smallest possible representation for member pointers

-Vmm	Support multiple inheritance for member pointers

-Vmp	Honor declared precision of member pointers

-Vms	Support single inheritance for member pointers

-Vmv	Place no restrictions on where member pointers can point (Default)

-Vx	Zero-length empty class member functions

-xdg	Use global destructor count (for compatibility with older versions of BCC32.EXE)

C++ options | Virtual tables

-V	Use smart C++ virtual tables (Default)

-V0	External C++ virtual tables

-V1	Public C++ virtual tables

C++ options | Templates

-Ja	Expand all template members (including unused members)

-Jgd	Generate definitions for all template instances and merge duplicates (Default)

-Jgx	Generate external references for all template instances

C++ options | Exception handling

-x	Enable exception handling (Default)

-xp	Enable exception location information

-xd	Enable destructor cleanup (Default)

-xf	Enable fast exception prologs

-xs	Enable slow exception epilogues

-RT	Enable runtime type information (Default)

Optimization options

-G, -G-	Optimize for size/speed; use – O1 and –O2 instead

-O	Optimize jumps

-O1	Generate smallest possible code

-O2	Generate fastest possible code

-Oc	Eliminate duplicate expressions within basic blocks and functions

-Od	Disable all optimizations

-Oi	Expand common intrinsic functions

-OS	Pentium instruction scheduling

-Og	Optimize for speed; use –O2 instead

-Os, -Ot	Optimize for speed/size; use –O2 and –O1 instead

-Ov	Enable loop induction variable and strength reduction

-Ox	Optimize for speed; use –O2 instead

Warning message options

-q	Suppress compiler identification banner (Default = OFF)

-w	Display warnings on

-wxxx	Enable xxx warning message

-w-xxx	Disable xxx warning message

-gn	Warnings: stop after n messages (Default = 100)

-gb	Stop batch compilation after first file with warnings (Default = OFF)

-jn	Errors: stop after n messages (Default = 25)

-jb	Stop batch compilation after first file with errors (Default = OFF)

Message options | Portability

-w-rpt	-w-8069	Nonportable pointer conversion (Default ON)

-w-cpt	-w-8011	Nonportable pointer comparison (Default ON)

-w-rng	-w-8068	Constant out of range in comparison (Default ON)

-wcln	-w8009	Constant is long

-wsig	-w8071	Conversion may lose significant digits

-wucp	-w8079	Mixing pointers to different 'char' types

Message options | ANSI violations

-w-voi	-w-8081	Void functions may not return a value (Default ON)

-w-ret	-w-8067	Both return and return of a value used (Default ON)

-w-sus	-w-8075	Suspicious pointer conversion (Default ON)

-wstu	-w8073	Undefined structure 'structure'

-w-dup	-w-8017	Redefinition of 'macro' is not identical (Default ON)

-w-big	-w-8007	Hexadecimal value contains more than three digits (Default ON)

-wbbf	-w8005	Bit fields must be signed or unsigned int

-w-ext	-w-8020	'identifier' is declared as both external and static (Default ON)

-w-dpu	-w-8015	Declare type 'type' prior to use in prototype (Default ON)

-w-zdi	-w-8082	Division by zero (Default ON)

-w-bei	-w-8006	Initializing 'identifier' with 'identifier' (Default ON)

-wpin	-w8061	Initialization is only partially bracketed

-wnak	-w8036	Non-ANSI Keyword Used: '<keyword>' (Note: Use of this option is a requirement for ANSI conformance)

Message options | Obsolete C++

-w-obi	-w-8052	Base initialization without a class name is now obsolete (Default ON)

-w-ofp	-w-8054	Style of function definition is now obsolete (Default ON)

-w-pre	-w-8063	Overloaded prefix operator 'operator' used as a postfix operator (Default ON)

Message options | Potential C++ errors

-w-nci	-w-8038	The constant member 'identifier' is not initialized (Default ON)

-w-ncl	-w-8039	Constructor initializer list ignored (Default ON)

-w-nin	-w-8042	Initializer for object 'identifier' ignored (Default ON)

-w-eas	-w-8018	Assigning ‘type’ to ‘enum’ (Default ON)

-w-hid	-w-8022	'function1' hides virtual function 'function2' (Default ON)

-wncf	-w-8037	Non-constant function ‘ident’ called for const object

-w-ibc	-w-8024	Base class 'class1' is also a base class of 'class2' (Default ON)

-w-dsz	-w-8016	Array size for 'delete' ignored (Default ON)

-w-nst	-w-8048	Use qualified name to access nested type 'type' (Default ON)

-whch	-w-8021	Handler for 'type1' Hidden by Previous Handler for 'type2'

-w-mpc	-w-8033	Conversion to type fails for members of virtual base class base (Default ON)

-w-mpd	-w-8034	Maximum precision used for member pointer type <type> (Default ON)

-w-ntd	-w-8049	Use '> >' for nested templates instead of '>>' (Default ON)

-w-thr	-w-8078	Throw expression violates exception specification (Default ON)

-w-tai	-w-8076	Template instance 'instance' is already instantiated (Default ON)

-w-tes	-w-8077	Explicitly specializing an explicitly specialized class member makes no sense (Default ON)

-w-nvf	-w-8051	Non-volatile function ‘function’ called for volatile object (Default ON)

Message options | Inefficient C++ coding

-w-inl	-w-8026, -w-8027	Functions containing ... are not expanded inline (Default ON)

-w-lin	-w-8028	Temporary used to initialize 'identifier' (Default ON)

-w-lvc	-w-8029, -w-8030, -w-8031, -w-8032	Temporary used for parameter (Default ON)

Message options | Potential errors

-w-ali	-w-8086	Incorrect use of #pragma alias “aliasName” = “substitutename” (Default ON)

-w-cod	-w-8093	Incorrect use of #pragma codeseg (Default ON)

-w-pcm	-w-8094	Incorrect use of #pragma comment (Default ON)

-w-mes	-w-8095	Incorrect use of #pragma message (Default ON)

-w-mcs	-w-8096	Incorrect use of #pragma code_seg (Default ON)

-w-pia	-w-8060	Possibly incorrect assignment (Default ON)

-wdef	-w8013	Possible use of 'identifier' before definition

-wnod	-w8045	No declaration for function 'function'

-w-pro	-w-8064, -w-8065	Call to function with no prototype (Default ON)

-w-rvl	-w-8070	Function should return a value (Default ON)

-wamb	-w8000	Ambiguous operators need parentheses

-wprc	-w8084	Suggest parentheses to clarify precedence (Default OFF)

-w-ccc	-w-8008	Condition is always true OR Condition is always false (Default ON)

-w-com	-w-8010	Continuation character \ found in // comment (Default ON)

-w-csu	-w-8012	Comparing signed and unsigned values (Default ON)

-w-nfd	-w-8040	Function body ignored (Default ON)

-w-ngu	-w-8041	Negating unsigned value (Default ON)

-w-nma	-w-8043	Macro definition ignored (Default ON)

-w-nmu	-w-8044	#undef directive ignored (Default ON)

-w-nop	-w-8046	Pragma option pop with no matching option push (Default ON)

-w-npp	-w-8083	Pragma pack pop with no matching pack push (Default ON)

-w-nsf	-w-8047	Declaration of static function 'function(...)' ignored (Default ON)

-w-osh	-w-8055	Possible overflow in shift operation (Default ON)

-w-ovf	-w-8056	Integer arithmetic overflow (Default ON)

-w-dig	-w-8014	Declaration ignored (Default ON)

-w-pck	-w-8059	Structure packing size has changed (Default ON)

-w-spa	-w-8072	Suspicious pointer arithmetic (Default ON)

-w-ifr	-w-8085	Function 'function' redefined as non-inline (Default ON)

-w-stl	-w-8087	‘operator==’ must be publicly visible to be contained by a ‘name’ (Default OFF)

-w-stl	-w-8089	‘operator<’ must be publicly visible to be contained by a ‘name’ (Default OFF)

-w-stl	-w-8090	‘operator<’ must be publicly visible to be used by a ‘name’ (Default OFF)

-w-stl	-w-8091,-w-8092	‘type’ argument ‘argument’ passed to ‘function’ is a ‘type’ iterator. ‘type’ iterator required (Default OFF)

Message options | Inefficient coding

-w-aus	-w-8004	'identifier' is assigned a value that is never used (Default ON)

-w-par	-w-8057	Parameter 'parameter' is never used (Default ON)

-wuse	-w8080	'identifier' declared but never used

-wstv	-w8074	Structure passed by value

-w-rch	-w-8066	Unreachable code (Default ON)

-w-eff	-w-8019	Code has no effect (Default ON)

Message options | General

-wasm	-w8003	Unknown assembler instruction

-w-ill	-w-8025	Ill-formed pragma (Default ON)

-w-ias	-w-8023	Array variable 'identifier' is near (Default ON)

-wamp	-w8001	Superfluous & with function

-w-obs	-w-8053	'ident' is obsolete (Default ON)

-w-pch	-w-8058	Cannot create precompiled header: ‘header‘ (Default ON)

-w-msg	-w-8035	User-defined warnings

-w-asc	-w-8002	Restarting compile using assembly (Default ON)

-w-nto	-w-8050	No type OBJ file present. Disabling external types option. (Default ON)

-w-pow	-w-8062	Previous options and warnings not restored (Default ON)

-w-onr	-w-8097	Not all options can be restored at this time (Default ON)


Linker options (alphabetical listing)

The following list shows the ILINK32 linker options in alphabetical order.

Option	Description

@xxxx	Uses the response file xxxx

/A:dd	Specifies file alignment (backward compatibility switch; use /Af)

/Af:nnnn	Specifies file alignment; set nnnn in hex or decimal (0x200 = 512 byte boundaries)

/Ao:nnnn	Specifies object alignment; set nnnn in hex or decimal (0x1000 = 4096 byte boundaries)

/aa	Builds a 32-bit Windows application

/ad	Builds a 32-bit Windows device driver

/ap	Builds a 32-bit Windows console application

/B:xxxx	Specifies image base address

/b:xxxx	Specifies image base address; preserves DLL relocation table

/C	Erases all linker-state files before each link

/c	Treats case as significant in symbols

/d	Delay loads a dll

/D:xxxx	Save specified description

/Enn	Specifies the number of max errors

/GC	Image comment string

/GD	Generates a DRC file

/GF:xxxx	Set image flags

/Gk	Keep output files on error

/Gl	Generate .LIB file

/Gpd	Generate design-time-only package

/Gpr	Generate runtime-only package

/Gn	Don’t generate state files (disable incremental linking)

/GS:string	Set section flags

/Gz	Calculate checksum of target and insert result in PE header

/H:xxxx	Specifies application heap reserve size

/Hc:nnnn	Specifies application heap commit size

/I	Specifies intermediate file output directory

/j	Specifies object search paths

/L	Specifies library search paths

/M	Mangled names in map file

/m	Creates map file with public names

/q	Supress command line banner

/r	Verbose linking

/Rr	Replace resources

/S:xxxx	Specifies application stack reserve size

/Sc:xxxx	Specifies application stack commit size

/s	Detailed map file of segments

/Tpd	Targets a Windows .DLL file

/Tpe	Targets a Windows .EXE file

/Tpp	Generate package

/t	Displays time spent on link

/Ud.d	Specifies user version(major,minor)

/Vd.d	Specifies expected Windows version

/v	Includes full symbolic debug information

/w	Turn all warnings on

/w-dee	Disables “.EXE module built with a .DLL or BPL extension” warning

/w-dpl	Disables “Duplicate symbol in library” warning

/w-dup	Disables “Duplicate symbol” warning

/w-exp	Enables “Attempt to export non-public symbol” warning

/w-nou	Disables “Creating a package without any units” warning

/w-rty	Enables “Unable to perform incremental link - performing full link” warning

/w-srd	Disables “Stripping relocations from a DLL may cause it to malfunction” warning

/w-snf	Disables “Section not found” warning

/w-uld	Disables “Unable to load DLL” warning

/x	Suppresses creation of map file

Default map file of segments (no linker switch, map file created by default)


Compiler-specific options

See also

Compiler-specific options can be used with all C and C++ programs. They directly affect how the compiler generates code.

The sub-topics are

Compiler define options

Compiler code generation options

Floating point options

Compiler output options

Source options

Debugging options

Precompiled header options

Assembler-code options


Compiler define options

See also

The macro definition capability of C++Builder lets you define and undefine macros (also called manifest or symbolic constants). The macros you define override those defined in your source files.

Defining macros

(Command-line switch: -Dname and -Dname=string)

The -Dname option defines the identifier name to the null string. -Dname=string defines name to string. In this assignment, string cannot contain spaces or tabs. You can also define multiple #define options on the command line using either of the following methods:

Include multiple definitions after a single -D option by separating each define with a semicolon (;) and assigning values with an equal sign (=). For example:

BCC32.EXE -Dxxx;yyy=1;zzz=NO MYFILE.C

Include multiple -D options, separating each with a space. For example:

BCC32.EXE -Dxxx -Dyyy=1 -Dzzz=NO MYFILE.C

Undefining macros

(Command-line switch = -Uname)

This command-line option undefines the previous definition of the identifier name.


Compiler code generation options

See also

Compiler Code Generation options affect how code is generated.

The options are

Instruction set

Calling convention

Data alignment

Treat enums as ints

Unsigned characters

Merge duplicate strings

Register variables

Code paging

Unicode application


Instruction set options

See also

The Instruction Set options specify for which CPU instruction set the compiler should generate code.

80386

(Command-line switch: -3)

Choose the 80386 option if you want the compiler to generate 80386 protected-mode compatible instructions running on Windows 95 or Windows NT.

i486

(Command-line switch: -4)

Choose the i486 option if you want the compiler to generate i486 protected-mode compatible instructions running on Windows 95 or Windows NT.

Pentium

(Command-line switch: -5)

Choose the Pentium option if you want the compiler to generate Pentium instructions on Windows 95 or Windows NT.

While this option increases the speed at which the application runs on Pentium machines, expect the program to be a bit larger than when compiled with the 80386 or i486 options. In addition, Pentium-compiled code will sustain a performance hit on non-Pentium systems.

Pentium Pro

(Command-line switch: -6)

Choose the Pentium Pro option if you want the compiler to generate Pentium Pro instructions running on Windows 95 or Windows NT.

Default = 80386  (-3)


Calling convention options

See also

Calling Convention options tell the compiler which calling sequences to generate for function calls. The C, Pascal, and Register calling conventions differ in the way each handles stack cleanup, order of parameters, case, and prefix of global identifiers.

You can use the _ _cdecl, _ _pascal, _ _fastcall, or _ _stdcall keywords to override the default calling convention on specific functions.

In C++Builder code, you will normally use the default C calling convention.

MSVC __fastcall

(Command-line switch: -pm)

This option tells the compiler to substitute the __msfastcall calling convention for any function without an explicitly declared calling convention.

C

(Command-line switch: -pc, -p-)

This option tells the compiler to generate a C calling sequence for function calls (generate underbars, case sensitive, push parameters right to left). This is the same as declaring all subroutines and functions with the _ _cdecl keyword. Functions declared using the C calling convention can take a variable parameter list (the number of parameters does not need to be fixed).

You can use the _ _pascal,  _ _fastcall, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Pascal

(Command-line switch: -p)

This option tells the compiler to generate a Pascal calling sequence for function calls (do not generate underbars, all uppercase, calling function cleans stack, pushes parameters left to right). This is the same as declaring all subroutines and functions with the _ _pascal keyword. The resulting function calls are usually smaller and faster than those made with the C (-pc) calling convention. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _fastcall, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Register

(Command-line switch: -pr)

This option forces the compiler to generate all subroutines and all functions using the Register parameter-passing convention, which is equivalent to declaring all subroutine and functions with the _ _fastcall keyword. With this option enabled, functions or routines expect parameters to be passed in registers.

You can use the _ _pascal, _ _cdecl, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Standard Call

(Command-line switch: -ps)

This option tells the compiler to generate a Stdcall calling sequence for function calls (does not generate underscores, preserve case, called function pops the stack, and pushes parameters right to left). This is the same as declaring all subroutines and functions with the _ _stdcall keyword. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _pascal, _ _fastcall keywords to specifically declare a function or subroutine using another calling convention.

Default = C  (-pc)


Data alignment options

See also

The Data Alignment options let you choose how the compiler aligns data in stored memory. Word, double word, and quad word alignment force integer-size and larger items to be aligned on memory addresses that are multiples of the type chosen. Extra bytes are inserted in structures to ensure that members align correctly.

Byte alignment

(Command-line switch: -a1 or -a-)

When byte alignment is on, the compiler does not force alignment of variables or data fields to any specific memory boundaries. The compiler aligns data at even or odd addresses, depending on the next available address.

While byte alignment produces more compact programs, the programs tend to run slower. The other data alignment options increase the speed at which 80x86 processors fetch and store data.

Word alignment (2-byte)

(Command-line switch: -a2)

When word alignment is on, the compiler aligns non-character data at even addresses. 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 even-numbered addresses.

Double word (4-byte)

(Command-line switch: -a4 or -a)

Double word alignment aligns non-character data at 32-bit word (4-byte) boundaries. Data with type sizes of less than four bytes are aligned on their type size.

Quad word (8-byte)

(Command-line switch: -a8)

Quad word alignment aligns non-character data at 64-bit word (8-byte) boundaries. Data with type sizes of less than eight bytes are aligned on their type size.

Paragraph (16-byte)

(Command-line switch: -a16)

Paragraph alignment aligns non-character data at 128-bit word (16-byte) boundaries. Data with type sizes of less than 16 bytes are aligned on their type size.

Default = Double word alignment (-a4 or -a)


Treat enums as ints option

See also

(Command-line switch: -b)

When the Treat Enums As Ints option is set, the compiler always allocates a whole word (a four-byte int for 32-bit programs) for enumeration types (variables of type enum).

When this option is off (-b-), the compiler allocates the smallest integer that can hold the enumeration values: the compiler allocates an unsigned or signed char if the values of the enumeration are within the range of 0 to 255 (minimum) or -128 to 127 (maximum), or an unsigned or signed short if the values of the enumeration are within the following ranges:

0 to 4,294,967,295 or -2,147,483,648 to 2,147,483,647

The compiler allocates a four-byte int (32-bit) to represent the enumeration values if any value is out of range.

Default = ON


Unsigned characters option

See also

(Command-line switch: -K)

When Unsigned Characters is set, the compiler treats char declarations as if they were unsigned char type, which provides compatibility with other compilers.

Default = OFF (char declarations default to signed; -K-)


Merge duplicate strings option

See also

(Command-line switch: -d)

When you set this option, the compiler merges two literal strings when one matches another. This produces smaller programs (at the expense of a slightly longer compile time), but can introduce errors if you modify one string.

Default = OFF (-d-)


Register variable option
Register variable options

See also

These options suppress or enable the use of register variables.

None

(Command-line switch: -r-)

None tells the compiler not to use register variables, even if you have used the register keyword.

Register keyword

(Command-line switch: -rd)

Register Keyword tells the compiler to use register variables only if you use the register keyword and a register is available. Use this option or the Automatic option (-r) to optimize the use of registers.

You can use -rd in #pragma options.

Automatic

(Command-line switch: -r)

Automatic tells the compiler to automatically assign register variables if possible, even when you do not specify a register variable by using the register keyword.

Generally, you can use Automatic, unless you are interfacing with preexisting assembly code that does not support register variables.

Default = Automatic (-r)


Code paging (MBCS)
Code paging (for MBCS)

(Command-line switch: -CP)

This option enables support for user-defined code pages. Its primary use is to let BCC32 know how to parse and convert multi-byte character strings (MBCS).

There are two distinct areas where code pages come into effect:

1.	String constants, comments, #error, and #pragma directives

2.	Wide-char string constants (as specified by L'<MBCS string>')

For MBCS strings belonging to the first set, you must specify the correct code page using a call to the Windows API function IsDBCSLeadByteEx. Using this function, specify the code page to correctly parse the MBCS strings for a particular locale (this, for example, enables BCC32 to correctly parse backslashes in MBCS trail bytes).

For MBCS strings belonging to the second set (wide-char string constants), specify the correct code page to convert the MBCS strings to Unicode strings using the Windows API function MultiByteToWideChar.

Syntax

Enable code paging with the following command-line switch:

-CPnnnn

In this syntax, nnnn is the decimal value of the code page you need to use for your specific locale.

The following rules apply:

When setting code paging, numeric settings for nnnn must adhere to the Microsoft NLS Code Page ID values. For example, use 437 for United States MS-DOS applications. Use 932 for Japanese.

The numeric value nnnn must be a valid code page supported by the OS.

The users may need to install the relevant Windows NLS files to make certain Asian locales and code pages accessible. Please refer to the Microsoft NLS Code Page documentation for specifics.

If you do not specify a code page value, BCC32 will call the Windows API function GetACP to retrieve the system's default code page, and will use this value when handling strings as indicated above.

Default = OFF


Unicode application

(Command-line switch: -WU)

This option creates a Unicode application from source code that uses the _txxxx macros in tchar.h. The macros are replaced with Unicode names if _UNICODE is enabled, and with non-Unicode names otherwise.

For example, the following code can be compiled as either a Unicode or a non-Unicode application. To compile it as a Unicode application, put the -WU switch on the command line.

#include <stdio.h>

#include <tchar.h>

int _tmain(char argc, _TCHAR ** _targv)

{

        _TCHAR buff[200];

        int i;

        for (i = 0; i < argc; i++)

        {

                _tcscpy(buff, _targv[i]);

                _tprintf(_T("argument %d:%s\n"), i, buff);

        }

        return 0;

}

In this example, _tcscpy is replaced by wcscpy if -WU is used, and by strcpy otherwise. Similarly, _tprintf is replaced by wprintf or printf, _TCHAR by wchar_t or char, and _targv by _wargv or _argv. The _T(...) macro turns the string in parentheses into a wide-character or standard string.

The tchar.h header file also maps _tWinMain to WinMain or wWinMain, and so forth. See tchar.h for a complete list of translations.

Default = OFF


Compiler floating point options

See also

Floating Point options tell the compiler how to handle floating-point code and floating-point optimization.

No floating point

(Command-line switch: -f-)

Use No Floating Point if you are not using floating point. No floating-point libraries are linked when this option is set (-f-). If you enable this option and use floating-point calculations in your program, you will get link errors. When unchecked (-f), the compiler emulates 80x87 calls at runtime.

Default = OFF  (-f)

Fast floating point

(Command-line switch: -ff)

When Fast Floating Point is on, floating-point operations are optimized without regard to explicit or implicit type conversions. Calculations can be faster than under ANSI operating mode.

The purpose of the fast floating-point option is to allow certain optimizations that are technically contrary to correct C semantics. For example,

double x;

x = (float) (3.5*x);

To execute this correctly, x is multiplied by 3.5 to give a double that is truncated to float precision, then stores as a double in x. Under the fast floating-point operation, the long double product is converted directly to a double. Since very few programs depend on the loss of precision on passing to a narrower floating-point type, fast floating point is the default.

When this option is disabled (-ff-), the compiler follows strict ANSI rules regarding floating-point conversions.

Default = ON

Correct Pentium FDIV flaw

(Command-line switch: -fp)

Some early Pentium chips do not perform specific floating-point division calculations with full precision. Although your chances of encountering this problem are slim, this switch inserts code that emulates floating-point division so that you are assured of the correct result. This option decreases your program's FDIV instruction performance.

Use of this option only corrects FDIV instructions in modules that you compile. The run-time library also contains FDIV instructions which are not modified by the use of this switch. To correct the run-time libraries, you must recompile them using this switch.

The following functions use FDIV instructions in assembly language which are not corrected if you use this option:

acos	cosh	pow10l

acosl	coshl	powl

asin	cosl	sin

asinl	exp	sinh

atan	expl	sinhl

atan2	fmod	sinl

atan2l	fmodl	tan

atanl	pow	tanh

cos	pow10	tanhl

tanl

In addition, this switch does not correct functions that convert a floating-point number to or from a string (such as printf or scanf).

Default = OFF


Compiler output options

See also

The following options control the compiler outputs

General compiler output options

Autodependency information

Generate underscores


General compiler output options

See also

Compile to .OBJ, no link

(Command-line switch = -c)

Compiles and assembles the named .C, .CPP, and .ASM files, but does not execute a link on the resulting .OBJ files.

Specify executable file name

(Command-line switch = -efilename)

Link file using filename as the name of the executable file. If you do not specify an executable name with this option, the linker creates an executable file based on the name of the first source file or object file listed in the command.

Pass option to linker

(Command-line switch = -lx)

Use this command-line option to pass option(s) x to the linker from a compile command. Use the command-line option -l-x to disable a specific linker option.

Create a MAP file

(Command-line switch = -M)

Use this compiler option to instruct the linker to create a map file.

Compile .OBJ to filename

(Command-line switch = -ofilename)

Use this option to compile the specified source file to filename.OBJ.

C++ compile

(Command-line switch = -P)

The -P command-line option causes the compiler to compile all source files as C++ files, regardless of their extension. Use -P- to compile all .CPP files as C++ source files and all other files as C source files.

The command-line option -Pext causes the compiler to compile all source files as C++ files and it changes the default extension to whatever you specify with ext. This option is provided because some programmers use different extensions as their default extension for C++ code.

The option -P-ext compiles files based on their extension (.CPP compiles to C++, all other extensions compile to C) and sets the default extension (other than .CPP).

Generate a multi-threaded target

(Command-line switch = -tWM)

The compiler creates a multi-threaded .EXE or .DLL. (The command-line option -WM is supported for backward compatibility only; it has the same functionality as -tWM.)

This option is not needed if you include a module definition file in your compile and link commands which specifies the type of 32-bit application you intend to build.


Autodependency information option

See also

(Command-line switch: -X-)

When the Autodependency option is set (-X-), the compiler generates autodependency information for all project files with a .C or .CPP extension.

The Borland C++Builder Project Manager uses autodependency information to speed up compilation times. The Project Manager opens the .OBJ file and looks for information about files included in the source code. This information is always placed in the .OBJ file when the source module is compiled. After that, the time and date of every file that was used to build the .OBJ file is checked against the time and date information in the .OBJ file. The source file is recompiled if the dates are different. This is called an autodependency check.

If the project file contains valid dependency information, the Project Manager does the autodependency check using that information. This is much faster than reading each .OBJ file.

When this option is disables (-X), the compiler does not generate the autodependency information.

Modules compiled with autodependency information can use MAKE's autodependency feature.

Note	The C++Builder Project Manager does not use autodependency information.

Default = OFF  (-X)


Generate underscores option

See also

(Command-line switch: -u)

When Generate Underscores option is set, the compiler automatically adds an underscore character (_) in front of every global identifier (functions and global variables) before saving them in the object module. Pascal identifiers (those modified by the _ _pascal keyword) are converted to uppercase and are not prefixed with an underscore.

Underscores for C and C++ are optional, but you should turn this option on to avoid errors if you are linking with the Borland C++ libraries.

Default = ON


Compiler source options

See also

Compiler source options tell the compiler how to interpret source code.

The options are

Source

Nested comments

Identifier Length

Language compliance

Borland extensions

ANSI

UNIX V

Kernighan and Ritchie

Compatibility

MFC compatibility


Nested comments option

See also

(Command-line switch: -C)

When Nested Comments is on, you can nest comments in your C and C++ source files.

Nested comments are not allowed in standard C implementations, and they are not portable.

Default = OFF


Identifier length option

See also

(Command-line switch: -in, where n = significant characters)

Use Identifier Length to specify the number of significant characters (those which will be recognized by the compiler) in an identifier.

Except in C++, which recognizes identifiers of unlimited length, all identifiers are treated as distinct only if their significant characters are distinct. This includes variables, preprocessor macro names, and structure member names.

Valid numbers for n are 0, and 8 to 250, where 0 means use the maximum identifier length of 250.

By default, C++Builder uses 250 characters per identifier. Other systems (including some UNIX compilers) ignore characters beyond the first eight. If you are porting to other environments, you might want to compile your code with a smaller number of significant characters, which helps you locate name conflicts in long identifiers that have been truncated.

Default = 250


Language compliance options

See also

The Language Compliance options tell the compiler how to recognize keywords in your programs.

Borland extensions

(Command-line switches: -A-, -AT)

Borland Extensions tells the compiler to recognize Borland's extensions to the C language keywords, including near, far, huge, asm, cdecl, pascal, interrupt, _export, _ds, _cs, _ss, _es, and the register pseudovariables (_AX, _BX, and so on). For a complete list of keywords, see the keyword index.

ANSI

(Command-line switch: -A)

The ANSI option compiles C and C++ ANSI-compatible code, allowing for maximum portability. Non-ANSI keywords are ignored as keywords.

UNIX V

(Command-line switch: -AU)

The UNIX V option tells the compiler to recognize only UNIX V keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Kernighan and Ritchie

(Command-line switch: -AK)

The Kernighan and Ritchie option tells the compiler to recognize only the K&R extension keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Hint:	If you get declaration syntax errors from your source code, check that this option is set to Borland Extensions.

Default = Borland Extensions  (-A-)


MFC compatibility option

See also

(Command-line switches: -VF)

Turn this option on to compile code that is compatible with the Microsoft foundation classes (MFC). Among other things, the compiler makes the following adjustments to be compatible with MFC:

Accepts spurious semicolons in a class scope

Allows anonymous structs

Uses the old-style scoping resolution in for loops

Allows methods to be declared with a calling convention, but leaves off the calling convention in the definition

Tries the operator new if it cannot resolve a call to the operator new[ ]

Lets you omit the operator & on member functions

Allows a const class that is passed by value to be treated as a trivial conversion, not as a user conversion

Allows you to use a cast to a member pointer as a selector for overload resolution, even if the qualifying type of the member pointer is not derived from the class in which the member function is declared

Accepts declarations with duplicate storage in a class, as in

extern "C" typedef

Accepts and ignores #pragma comment(linker, "...") directives

Note:	The -VF option is not compatible with – A.

Setting the -VF option implies that the –Vd switch (old style scoping in for loops) is on. If you turn on the –VF switch, you do not need to turn on – Vd.

Default = OFF


MSVC compatibility option

See also

(Command-line switches: -VM)

Substitutes __msfastcall for __fastcall calling convention. This switch should not be used when working with a VCL application. It will cause numerous linker errors.


Compiler debugging options

See also

Compiler Debugging options affect the generation of debug information during compilation. When linking larger .OBJ files, you may need to turn these options off to increase the available system resources.

The options are

Standard stack frame

Out-of-line inline functions

Line numbers

Debug information in OBJs


Standard stack frame option

See also

(Command-line switch: -k)

When the Standard Stack Frame option is on, the compiler generates a standard stack frame (standard function entry and exit code). This is helpful when debugging, since it simplifies the process of stepping through the stack of called subroutines.

When this option is off, any function that does not use local variables and has no parameters is compiled with abbreviated entry and return code. This makes the code smaller and faster.

The Standard Stack Frame option should always be on when you compile a source file for debugging.

Default = ON


Out-of-line inline functions option

See also

(Command-line switch: -vi)

When the Out-of-line Inline Functions option is on, the compiler expands C++ inline functions inline.

To control the expansion of inline functions, the Debug Information In OBJs option (-v) acts slightly different for C++ code: when inline function expansion is disabled, inline functions are generated and called like any other function.

Because debugging with inline expansion can be difficult, the following command-line options are provided:

-v turns debugging on and inline expansion off

-v- turns debugging off and inline expansion on

-vi turns inline function expansion on

-vi- turns inline expansion off (inline functions are expanded out of line)

For example, if you want to turn both debugging and inline expansion on, use the -v and -vi options.

Default = OFF


Line numbers option

See also

(Command-line switch: -y)

When the Line Numbers option is on, the compiler automatically includes line numbers in the object and object map files. Line numbers are used by both the integrated debugger and Turbo Debugger.

Although the Debug Info in OBJs option (-v) automatically generates line number information, you can turn that option off (-v-) and turn on Line Numbers (-y) to reduce the size of the debug information generated. With this setup, you can still step, but you will not be able to watch or inspect data items.

Including line numbers increases the size of the object and map files but does not affect the speed of the executable program.

When Line Numbers is on, make sure you turn off Pentium scheduling in the Compiler options. When this option is set, the source code will not exactly match the generated machine instructions, which can make stepping through code confusing.

Default = OFF


Debug information in OBJs option

See also

(Command-line switch: -v)

When the Debug Info In OBJs option is on, debugging information is included in your .OBJ files. The compiler passes this option to the linker so it can include the debugging information in the .EXE file. For debugging, this option treats C++ inline functions as normal functions.

You need debugging information to use either the integrated debugger or the standalone Turbo Debugger.

When this option is off (-v-), you can link and create larger object files. While this option does not affect execution speed, it does affect compilation and link time.

When Line Numbers is on, make sure you turn off Pentium scheduling in the Compiler options. When this option is set, the source code will not exactly match the generated machine instructions, which can make stepping through code confusing.

Default = ON


Precompiled header options

See also

Precompiled header files can dramatically increase compilation speed by storing an image of the symbol table on disk in a file, then later reloading that file from disk instead of parsing all the header files again. Directly loading the symbol table from disk is much faster than parsing the text of header files, especially if several source files include the same header file.

The options are

General usage

Cache precompiled header

Smart-cached precompiled header

Generate external type files (precompiled headers)

Precompiled header name

Stop precompiling after header file


General precompiled header options

See also

Precompiled headers can dramatically increase compilation speeds, although they require a considerable amount of disk space.

Generate and use

(Command-line switch: -H)

When you set this option, the IDE generates and uses precompiled headers. The default file name is <projectname>.CSM for IDE projects, and is BC32DEF.CSM for command-line compiles.

Use but do not generate

(Command-line switch: -Hu)

When the Use But Do Not Generate option is set, the compilers use preexisting precompiled header files; new precompiled header files are not generated.

Do not generate or use

(Command-line switch: -H-)

When the Do Not Generate Or Use option is on, the compilers do not generate or use precompiled headers.

Default = Do not generate or use  (-H-)


Cache precompiled header option

See also

(Command-line switch: -Hc)

When you enable this option, the compiler caches the precompiled headers it generates. This is useful when you are precompiling more than one header file.

To use this option, you must also enable the Generate and Use (-H) precompiled header option.

Default = OFF


Smart-cached precompiled header option

See also

(Command-line switch: -Hs)

When you enable this option, the compiler smart-caches the precompiled headers it generates (smart-caching uses less memory than regular caching option -Hc). Caching your header files in memory is useful when you are precompiling more than one header file.

Default = ON


Generate external type files (precompiled headers)

See also

(Command-line switch: -He)

When this option is set, the compiler generates a file or files that contain debug type information for all the symbols contained in the precompiled headers. The files end with the .#xx extension, where xx is 00 for the first file generated and is incremented for each additional type-information file required.

Using this option dramatically decreases the size of your .OBJ files, since debug type information is centralized and is not duplicated in each .OBJ file.

Default = ON


Precompiled header name option

See also

(Command-line switch: -H=filename)

This option lets you specify the name of your precompiled header file. The compilers set the name of the precompiled header to filename.

When this option is set, the compilers generate and use the precompiled header file that you specify.


Stop precompiling after header file option

See also

(Command-line switch: -Hh=xxx or -H\"xxx\")

This option terminates compiling the precompiled header after processing the file specified as xxx. You can use this option to reduce the disk space required for precompiled headers.

The -Hh sytnax is generally easier to use than the -H syntax. Whichever version you choose, you need to quote long file names. Examples:

-Hh=mycsm.csm

-H\"mycsm.csm\"

-Hh="c:\program files\mycsm.csm"

-H\"c:\program files\mycsm.csm\"

When you use this option, the file you specify must be included from a source file for the compiler to generate a .CSM file.

You can also use #pragma hdrstop within your .CPP files to specify when to stop the generation of precompiled headers.

You cannot specify a header file that is included from another header file. For example, you cannot list a header included by windows.h because this would cause the precompiled header file to be closed before the compilation of windows.h was completed.


Assembler_code options
Assembler-code options

See also

Compile to .ASM, then assemble

(Command-line switch = -B)

This command-line option causes the compiler to first generate an .ASM file from your C++ (or C) source code (same as the -S command-line option). The compiler then calls TASM32 (or the assembler specified with the -E option) to create an .OBJ file from the .ASM file. The .ASM file is then deleted. To use this 32-bit compiler option, you must install a 32-bit assembler, such as TASM32.EXE, and then specify this assembler with the -E option.

Your program will fail to compile with the -B option if your C or C++ source code declares static global variables that are keywords in assembly. This is because the compiler does not precede static global variables with an underscore (as it does other variables), and the assembly keywords will generate errors when the code is assembled.

Specify assembler

(Command-line switch = -Efilename)

Assemble instructions using filename as the assembler. The 32-bit compiler uses TASM32 as the default assembler.

Compile to assembler

(Command-line switch = -S)

This option causes the compiler to generate an .ASM file from your C++ (or C) source code. The generated .ASM file includes the original C or C++ source lines as comments in the file.

Specify assembler option

(Command-line switch = -Tx)

Use this command-line option to pass the option(s) x to the assembler you specify with the -E option. To disable all previously enabled assembler options, use the -T- command-line option.


Search directories

See also

The search directory options let you specify the directories that contain your standard include files, library and .OBJ files, and program source files.

Include

(Command-line equivalent: -Ipath, where path = directory path)

Use this option to specify the drive and/or directories that contain program include files. Standard include files are those you specify in angle brackets (<>) in an #include statement (for example, #include <myfile>).

The Borland compilers and linkers use specific file search algorithms to locate the files needed to complete the compilation and link cycles.

Library

(Command-line equivalent: -Lpath, where path = directory path)

Use the Library option to specify the directories that contain the C++Builder startup object files (C0x.OBJ), run-time library files (.LIB files), and all other .LIB files. By default, the linker looks for them in the directory containing the project file (or in the current directory if you’re using the command-line compiler).

You can also use the linker option /Lpath to specify the library search directories when you link files from the command line.

Specifying multiple directories

You can specify multiple directory names from the command line by using a semicolon (;) to separate the specified drives and directories:

You can stack multiple entries with a single -L or -I option by separating directories with a semicolon:

BCC32.EXE -Ldirname1;dirname2;dirname3 -Iinc1;inc2;inc3 myfile.c

You can place more than one of each option on the command line, like this:

BCC32.EXE -Ldirname1 -Ldirname2 -Iinc1 -Iinc2 -Iinc3 myfile.c

You can mix listings:

BCC32.EXE -Ldir1;dir2 -Iinc1 -Ld:dir3 -Iinc2;inc3 myfile.c

If you list multiple -L or -I options on the command line, the result is cumulative; the compiler searches all the directories listed in order from left to right.


File search algorithms

See also

#include-file search algorithms

The Borland C++ compiler searches for files included in your source code with the #include directive in the following ways:

If you specify a path and/or directory with your include statement, the compiler searches only the location specified. For example, if you have the following statement in your code:

   #include "c:\CBuilder\include\vcl\vcl.h"

the header file vcl.h must reside in the directory C:\ CBuilder\INCLUDE. In addition, if you use the statement:

   #include <vcl\vcl.h>

and you set the Include option (-I) to specify the path c:\CBuilder\include, the file vcl.h must reside in C:\CBuilder\INCLUDE\VCL, and not in C:\CBuilder\INCLUDE or C:\VCL.

If you put an #include <somefile> statement in your source code, the compiler searches for "somefile" only in the directories specified with the Include (-I) option.

If you put an #include "somefile" statement in your code, the compiler will search for "somefile" in the following order:

1. the same directory as the file containing the #include statement.

2. the directories of files that include (#include) that file.

3. the current directory

4. the directories specified with the Include (-I) option.

Library file search algorithms

The library file search algorithms are similar to those for include files:

Implicit libraries: The Borland C++ compiler searches for implicit libraries only in the specified library directories; this is similar to the search algorithm for #include <somefile>.

Implicit library files are the ones the compiler automatically links in and the start-up object file (C0x.OBJ).

Explicit libraries: Where the compiler searches for explicit (user-specified) libraries depends in part on how you list the library file name. Explicit library files are 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: mylib.lib), the compiler first searches for that library in the current directory. If the first search is unsuccessful, the compiler looks in the directories specified with the Library (-L) option. This is similar to the search algorithm for #include "somefile".

If you list a user-specified library with drive and/or directory information (like this: c:\mystuff\mylib1.lib), C++Builder searches only in the location you explicitly listed as part of the library path name and not in any specified library directories.


C++-specific options

See also

The C++ options affect compilation of all C and C++ programs. For most of the C++ options, you'll usually want to use the default settings.

The subtopics are

C++ compatibility options

Virtual table options

Template options

Exception handling/RTTI options


C++ compatibility options

See also

Use the C++ Compatibility options to handle C++ compatibility issues, such as handling char types, specifying options about hidden pointers, passing class arguments, adding hidden members and code to a derived class, passing the this pointer to Pascal member functions, changing the layout of classes, or ensuring compatibility when class instances are shared with non-C++ code or code compiled with previous versions of Borland C++.

Don't restrict scope of 'for' loop expression variables

Calling convention mangling compatibility

Zero-length empty base classes

Zero-length empty class member functions

Old-style structure layout

Member pointer representation


Don't restrict scope of 'for' loop expression variables option

See also

(Command-line switch: -Vd)

This option lets you specify the scope of variables declared in for loop expressions. The output of the following code segment changes, depending on the setting of this option.

int main(void)

{

for(int i=0; i<10; i++)

{

      cout << "Inside for loop, i = " << i << endl;

}     //end of for-loop block

cout << "Outside for loop, i = " << i << endl;  //error without -Vd

}      //end of block containing for loop

If this option is disabled (the default), the variable i goes out of scope when processing reaches the end of the for loop. Because of this, you'll get an Undefined Symbol compilation error if you compile this code with this option disabled.

If this option is set (-Vd), the variable i goes out of scope when processing reaches the end of the block containing the for loop. In this case, the code output would be:

Inside for loop, i = 0

...

Outside for loop, i = 10

Default = OFF


Calling convention mangling compatibility option

See also

(Command-line switch: -VC)

When this option is set, the compiler disables the distinction of function names where the only possible difference is incompatible code generation options. For example, with this option set, the linker will not detect if a call is made to a _ _fastcall member function with the cdecl calling convention.

This option is provided for backward compatibility only; it lets you link old library files that you cannot recompile.

Default = OFF


Zero-length empty base classes

See also

(Command-line switch: -Ve)

Usually the size of a class is at least one byte, even if the class does not define any data members. When you set this option, the compiler ignores this unused byte for the memory layout and the total size of any derived classes; empty base classes will not consume space in derived classes.

Default = OFF


Zero-length empty class member functions
Zero-length class member functions

See also

(Command-line switch: -Vx)

Usually the size of a data member in a class definition is at least one byte. When this option is enabled, the compiler allows an empty structure of zero length.

Default = OFF


Old-style structure layout

See also

(Command-line switch: -Vl)

This is a backward compatibility switch that causes the BCC32 C++ compiler to lay out derived classes the same way it did in older versions of Borland C++. Enable this option if you need to compile source files that you intend to use with older versions of Borland C++ (for example, if you need to work with a .DLL that you cannot recompile, or if you have older data files that contain hardwired class layouts).

Default = OFF


Member pointer representation

See also

Use Member Pointers options to direct member pointers and affect how the compiler treats explicit casts.

Support all cases

(Command-line switch: -Vmv)

When this option is enabled, the compiler places no restrictions on where member pointers can point. Member pointers use the most general (but not always the most efficient) representation.

Default = ON

Support multiple inheritance

(Command-line switch: -Vmm)

When this option is enabled, member pointers can point to members of multiple inheritance classes (with the exception of virtual base classes).

Default = OFF

Support single inheritance

(Command-line switch: -Vms)

When this option is enabled, member pointers can point only to members of base classes that use single inheritance.

Default = OFF

Smallest for class

(Command-line switch: -Vmd)

When this option is enabled, member pointers use the smallest possible representation that allows them to point to all members of their particular class. If the class is not fully defined at the point where the member pointer type is declared, the most general representation is chosen by the compiler and a warning is issued.

Default = OFF

Honor declared precision

(Command-line switch: -Vmp)

When this option is enabled, the compiler uses the declared precision for member pointer types. Use this option when a pointer to a derived class is explicitly cast as a pointer-to-member of a simpler base class (when the pointer is actually pointing to a derived class member).

Default = OFF


Virtual table options

See also

The virtual tables options control C++ virtual tables and the expansion of inline functions when debugging.

Smart

(Command-line switch: -V)

This option generates common C++ virtual tables and out-of-line inline functions across the modules in your application. As a result, only one instance of a given virtual table or out-of-line inline function is included in the program.

The Smart option generates the smallest and most efficient executables, but produces .OBJ and .ASM files compatible only with Borland linkers and assemblers.

Default = ON

External

(Command-line switch: -V0)

You use the External option to generate external references to virtual tables. If you don’t want to use the Smart or Local options, use the External and Public options to produce and reference global virtual tables.

When you use this option, one or more of the modules comprising the program must be compiled with the Public option to supply the definitions for the virtual tables.

Default = OFF

Public

(Command-line switch: -V1)

Public produces public definitions for virtual tables. When using the External option (-V0), at least one of the modules in the program must be compiled with the Public option to supply the definitions for the virtual tables. All other modules should be compiled with the External option to refer to that Public copy of the virtual tables.

Default = OFF


Template options

See also

The Template options specify how the compiler generates template instances in C++.

Smart

(Command-line switch: -Jgd)

When the Smart option is set, the compiler generates public (global) definitions for all template instances. If more than one module generates the same template instance, the linker automatically merges duplicates to produce a single copy of the instance.

To generate the instances, the compiler must have available the function body (in the case of a template function) or the bodies of member functions and definitions for static data members (in the case of a template class), typically in a header file.

This is a convenient way of generating template instances.

Default = ON

External

(Command-line switch: -Jgx)

When the External option is set, the compiler generates external references to all template instances.

If you use this option, all template instances that need to be linked must have an explicit instantiation directive in at least one other module.

Default = OFF


C++ Options|Exception handling/RTTI (Project Options)
Exception handling/RTTI options

See also

Use the Exceptions Handling options to enable or disable exception handling and to tell the compiler how to handle the generation of run-time type information.

If you use exception handling constructs in your code and compile with exceptions disabled, you'll get an error.

The options are

Enable exceptions

Exception handling options

Enable run-time type information


Enable Exceptions (Project Options)
Enable exceptions option

See also

(Command-line switch: -x)

When this option is set, C++ exception handling is set. If this option is disabled (-x-) and you attempt to use exception handling routines in your code, the compiler generates error messages during compilation.

Disabling this option makes it easier for you to remove exception handling information from programs; this might be useful if you are porting your code to other platforms or compilers.

Disabling this option turns off only the compilation of exception handling code; your application can still include exception code if you link .OBJ and library files that were built with exceptions enabled (such as the Borland runtime libraries).

Default = ON


Exception Handling (Project Options)
Exception handling options

See also

Enable exception location information

(Command-line switch: -xp)

When this option is set, run-time identification of exceptions is available because the compiler provides the file name and source-code line number where the exception occurred. This enables the program to use the __ThrowFileName global to obtain the file where the exception occurred and the __ThrowLineNumber global to access the line number from where the C++ exception was thrown.

Default = OFF

Enable destructor cleanup

(Command-line switch: -xd)

When this option is set and an exception is thrown, destructors are called for all automatically declared objects between the scope of the catch and throw statements.

In general, when you set this option, you should also set Enable Runtime Type Information (-RT) as well.

Destructors are not automatically called for dynamic objects allocated with new, and dynamic objects are not automatically freed.

Default = ON

Enable fast exception prologs

(Command-line switch: -xf)

When this option is set, inline code is expanded for every exception handling function. This option improves performance at the cost of larger executable file sizes.

Default = OFF

Enable slow exception epilogues

(Command-line switch: -xs)

When this option is set, the exception handling epilogue code is not expanded inline. This option decreases performance slightly.

Default = OFF


Enable Runtime Type Information (Project Options)
Enable run-time type information option

See also

(Command-line switch: -RT)

This option causes the compiler to generate code that allows run-time type identification.

In general, if you set Enable Destructor Cleanup (-xd), you will need to set this option as well.

Default = ON


Linker options

See also

Linker options let you control how the linkers combine intermediate files (.OBJ, .LIB, and .RES) into executable (.EXE) and dynamic-link library (.DLL) files. You will usually want to keep the default settings for most options in this section.

The linker options can be broken into the following subtopics

General options

Map file options

Path options

Image options


Linker general options

The following options are available to control the input to your link cycles:

Clear state files before linking

Warning options

Max Error

Verbose linking

Suppress banner

Case-sensitive link

Include debug information

No state files (disable incremental linking)

Generate import library

Generate DRC file

Keep output files on error


Clear state files before linking

(Command-line switch = /C)

This switch, when set, deletes the existing incremental linker state files and then recreates these files and continues with the link. This option allows you to refresh the state files.

Default = OFF


Case-sensitive link

(Command-line switch = /c)

When the Case-sensitive Link option is set, the linker differentiates between upper and lower-case characters in public and external symbols. Normally, this option should be set, since C and C++ are both case-sensitive languages.

Default = ON


No state files

(Command-line switch = /Gn)

This switch suppresses the generation of linker state files, disabling incremental linking. If you use /Gn, subsequent links will take just as long as the first one.

Default = OFF


Maximum number of errors

(Command-line switch = /Enn)

This switch allows you to set the number of errors encountered before the link is aborted. nn is the user specified number of errors.

No Default


Verbose linking

(Command-line switch = /r)

When this switch is set, the verbose option is set for rlink32 and detailed information is emitted during the resource link.

Default = OFF


Suppress banner

(Command-line switch = /q)

This switch allows you to turn off ilink32’s command-line banner.

Default = OFF


Include debug information

(Command-line switch = /v)

When the Include Debug Information option is on, the linker includes information in the output file needed to debug your application with the C++Builder integrated debugger or Turbo Debugger.

On the command line, this option causes the linker to include debugging information in the executable file for all object modules that contain debugging information. You can use the /v+ and /v- options to selectively enable or disable debugging information on a module-by-module basis (but not on the same command-line where you use /v). For example, the following command includes debugging information for modules mod2 and mod3, but not for mod1 and mod4:

ILINK32 mod1 /v+ mod2 mod3 /v- mod4

Default = ON in IDE; OFF on the command line


Linker warnings

Warning options enable or disable the display of ILINK32 warnings. The warnings are

Public symbol 'symbol' defined in both module 'module1' and 'module2' (Duplicate symbols in library)

Public symbol 'symbol' defined in both module 'module1' and 'module2' (Duplicate symbols)

Attempt to export non-public symbol

Unable to perform incremental link – perfroming full link

Creating a package without any units

Unable to load DLL

Stripping relocations from a DLL may cause the DLL to malfunction

Section not found

Image linked as .an executable but with .DLL or BPL extension


Generate import library

(Command-line switch = /Gi)

This option generates an import library for a dll during the link cycle.

Default = ON in the IDE, OFF on the command line.


Generate DRC files
Generate DRC file

(Command-line switch = /GD)

When this option is set, ILink32 will generate Delphi compatible .RC files (DRC files). The DRC file will be the same name as the exe file, and will be emitted to the same directory as the exe file.

Default = OFF


Keep output files on error

(Command-line switch = /Gk)

The /Gk option tells the linker to keep output files that would otherwise be deleted on errors.  The linker has been changed to delete its output file (EXE/DLL) if there are errors in the link.  The old behavior was to leave these files and not delete them.

Default = OFF


Map file options

Linker map file options tell the linker what type of map file to produce. These options control the information generated on segment ordering, segment sizes, and public symbols.

By default, the linker creates a map file that contains general segment information, which includes a list of segments, the program start address, and any warning or error messages produced during the link.

For settings other than Off, the map file is placed in the directory where the project makefile is stored.

The map file options are:

Off      (default Segments map file not created)

Publics map

Detailed segments map

Mangled names


Off option (linker map file)
Off option (map file)

(Command-line switch = /x)

This switch turns off the creation of the default linker map file.

By default, the linker generates a map file with that contains general segment information that includes a list of segments, the program start address, and any warning or error messages produced during the link. There is no switch for this setting. Use the /x option to suppress the creation of the default map file.

Default = OFF (Default map file is created)


Publics map option

(Command-line switch = /m)

This option instructs the linker to produce a map file that contains an overview of the application segments and two listings of the public symbols.

The segments listing has a line for each segment, showing the segment starting address, segment length, segment name, and the segment class.

The public symbols are broken down into two lists, the first showing the symbols in sorted alphabetically, the second showing the symbols in increasing address order. Symbols with absolute addresses are tagged Abs.

A list of public symbols is useful when debugging: many debuggers use public symbols, which lets you refer to symbolic addresses while debugging.


Detailed segments map option

(Command-line switch = /s)

The Detailed Segments option creates the most comprehensive map file by adding a detailed map of segments to the map file created with the Publics option (/m). The detailed list of segments contains the segment class, the segment name, the segment group, the segment module, and the segment ACBP information. If the same segment appears in more than one module, each module appears as a separate line.

The ACBP field encodes the A (alignment), C (combination), and B (big) attributes into a set of four bit fields, as defined by Intel. ILINK32 uses only three of the fields: A, C, and B. The ACBP value in the map is printed in hexadecimal. The following field values must be ORed together to arrive at the ACBP value printed.

Field	Value	Description

A (alignment)	00	An absolute segment

20	A byte-aligned segment

40	A word-aligned segment

60	A paragraph-aligned segment

80	A page-aligned segment

A0	An unnamed absolute portion of storage

C (combination)	00	Cannot be combined

08	A public combining segment

B (big)	00	Segment less than 64K

02	Segment exactly 64K

With the Segments options set, public symbols with no references are flagged idle. An idle symbol is a publicly defined symbol in a module that was not referenced by an EXTDEF record or by any other module included in the link. For example, this fragment from the public symbol section of a map file indicates that symbols Symbol1 and Symbol3 are not referenced by the image being linked:

0002:00000874     Idle     Symbol1

0002:00000CE4              Symbol2

0002:000000E7     Idle     Symbol3


Mangled names option (map file)

(Command-line switch = /M)

Prints the mangled C++ identifiers in the map file, not the full name. This can help you identify how names are mangled (mangled names are needed as input by some utilities).

Default = OFF


Linker Path options

The following options are available to control the input to your link cycles:

Intermediate file output path

Object search paths

Library search paths


Intermediate file output paths

(Command-line switch = /I)

The -I switch tells the linker to place intermediate output files in the directory specified.  Currently files that qualify for this placement are the linker state files.  The .MAP file and .TDS files will go to the same directory as the output image, unless otherwise specified for the .MAP file.


Library search paths

This option lets you specify the directories the linker will search if there is no explicit path given for an .LIB module in the compile/link statement.

The Specify Library Search Path uses the following command-line syntax:

/L<PathSpec>[;<PathSpec>][...]

The linker uses the specified library search path(s) if there is no explicit path given for the .LIB file and the linker cannot find the library file in the current directory. For example, the command

ILINK32 /Lc:\mylibs;.\libs splash .\common\logo,,,utils logolib

directs the linker to first search the current directory for SPLASH.LIB. If it is not found in he current directory, the linker then searches for the file in the C:\MYLIBS directory, and then in the .\LIBs directory. However, notice that the linker does not use the library search paths to find the file LOGO.LIB because an explicit path was given for this file.


Object search paths

See also

(Command-line switch = /j)

This option lets you specify the directories the linker will search if there is no explicit path given for an .OBJ module in the compile/link statement.

The Specify Object Search Path uses the following command-line syntax:

/j<PathSpec>[;<PathSpec>][...]

The linker uses the specified object search path(s) if there is no explicit path given for the .OBJ file and the linker cannot find the object file in the current directory. For example, the command

ILINK32 /jc:\myobjs;.\objs splash .\common\logo,,,utils logolib

directs the linker to first search the current directory for SPLASH.OBJ. If it is not found in he current directory, the linker then searches for the file in the C:\MYOBJS directory, and then in the .\OBJs directory. However, notice that the linker does not use the object search paths to find the file LOGO.OBJ because an explicit path was given for this file.


Linker image options

The following options are available to control the input to your link cycles:

Delay load a .DLL

File alignment (in hexadecimal)

Object alignment (in hexadecimal)

Application target options

Image base address (in hexadecimal)

Reserved heap size (in hexadecimal)

Commit heap size (in hexadecimal)

Reserved stack size (in hexadecimal)

Commit stack size (in hexadecimal)

Set image description

Subsystem version (major.minor)

User version (major.minor)

Image comment string

Set image flags

Package options

Set section flags

Calculate checksum

Replace resources


Delay load a DLL

(Command-line switch = /d)

Delayed loading of DLLs is useful for DLLs that are very infrequently used by an application, but might have high startup costs.  DLLs which have been delay loaded will not be loaded and initialized until an entrypoint in the DLL is actually called.  There is accompanying RTL support for delayed load DLLs which the user can hook into to handle errors on loading, and to supplant the delayed load system, if so desired.

  ilink32 /dMyDataBase.dll c0x32 x ,x,,import32 cw32mt MyDataBase.lib

Default = OFF


File alignment
File alignment (in hexadecimal)

(Command-line switch = /Af:xxxx)

The File Alignment option specifies page alignment for code and data within the executable file. The linker uses the file alignment value when it writes the various objects and sections (such as code and data) to the file. For example, if you use the default value of 0x200, the linker stores the section of the image on 512-byte boundaries within the executable file.

When using this option, you must specify a file alignment value that is a power of 2, with the smallest value being 16.

The old style of this option (/A:dd) is still supported for backward compatibility. With this option, the decimal number dd is multiplied by the power of 2 to calculate the file alignment value.

The command-line version of this option (/Af:xxxx) accepts either decimal or hexadecimal numbers as the file alignment value. The value setting is 512 (0x200).

Default = 512 (0x200)


Object alignment
Object alignment (in hexadecimal)

(Command-line switch = /Ao:xxxx)

The linker uses the object alignment value to determine the virtual addresses of the various objects and sections (such as code and data) in your application. For example, if you specify an object alignment value of 8192, the linker aligns the virtual addresses of the sections in the image on 8192-byte (0x2000) boundaries.

When using this option, you must specify an object alignment value that is a power of 2, with the smallest value being 4096 (the default).

The command-line version of this option (/Ao:xxxx) accepts either decimal or hexadecimal numbers as the object alignment value.

Default = 4096 (0x1000)


Application target options

See also

The following options tell the linkers what type of application image to build.

The following options are not needed if you include a module definition file in your compile and link commands that specifies the type of 32-bit application you intend to build, except for device drivers. If your target type is a device driver, the /ad option must be passed to the linker directly and can not be set in the module definition file.

Link using 32-bit Windows API

(Command-line switch = /aa)

The linker generates a protected-mode executable that runs using the 32-bit Windows API.

Link for 32-bit Windows device driver

(Command-line switch = /ad)

When you use this switch, the application type is set to NATIVE, and the image checksum is calculated and set.

Link for 32-bit console application

(Command-line switch = /ap)

The linker generates a 32-bit protected-mode executable file that runs in console mode.

Link 32-bit .DLL file

(Command-line switch = /Tpd)

The linker generates a 32-bit protected-mode Windows .DLL file.

Link 32-bit .EXE file

(Command-line switch = /Tpe)

The linker generates a 32-bit protected-mode Windows .EXE file.

Generate package (/Tpp)


Image base address (in hexadecimal)
Image base address

The following switches allow you to specify a base address for an executable or library. (The default address is 0x400000 for Win32 systems.) These options improve both load-time and runtime performance, since the operating system no longer has to apply internal fixups.

These switches accept either decimal or hexadecimal numbers as the image base address.

/b is the preferred switch for this purpose.

Specify image base address

(Command-line switch = /b:xxxx)

Use this option to specify an image base address for your executable or DLL. The load address of the first object in the application or library is set to the number you specify, if possible, and all successive objects are aligned on 64K linear address boundaries; internal fixups are ignored. However, if the module cannot be loaded using the specified address, the operating system reverts to its default setting and applies internal fixups.

Default = OFF

Specify image base address; remove relocation table

(Command-line switch = /B:xxxx)

/B does the same thing as /b, except that it discards the module’s relocation table. Internal fixups are removed from the image and the requested load address of the first object in the application is set to the number you specify. Although this option can reduce the size of your final application module, it is not recommended for producing DLLs.

Default = OFF


Reserve stack size
Reserved stack size

(Command-line switch = /S:xxxx)

Use this option to specify the size of the reserved stack in hexadecimal or decimal. The minimum allowable value for this field is 4K (0x1000).

Specifying the reserved stack size here overrides any STACKSIZE setting in a module definition file.

Default = 1Mb (0x1000000)


Commit stack size
Committed stack size

(Command-line switch = /Sc:xxxx)

Use this option to specify the size of the committed stack in hexadecimal or decimal. The minimum allowable value for this field is 4K (0x1000) and any value specified must be equal to or less than the Reserved Stack Size setting (/S).

Specifying the committed stack size here overrides any STACKSIZE setting in a module definition file.

Default = 8K (0x2000)


Reserved heap size

(Command-line switch = /H:xxxx)

Use this option to specify the size of the reserved heap in hexadecimal or decimal. The minimum allowable value for this field is 0.

Specifying the reserved heap size here overrides any HEAPSIZE setting in a module definition file.

Default = 1Mb (0x1000000)


Commited heap size
Committed heap size

(Command-line switch = /Hc:xxxx)

Use this option to specify the size of the committed heap in hexadecimal or decimal. The minimum allowable value for this field is 0 and any value specified must be equal to or less than the Reserved Heap Size setting (/H).

Specifying the committed heap size here overrides any HEAPSIZE setting in a module definition file.

Default = 4K (0x1000)


Set image description

(Command-line switch = /D:xxxx)

Saves the specified description in the PE image.

Default = OFF


Subsystem version
Subsystem version (major.minor)

(Command-line switch = /Vd.d)

This option lets you specify the Windows version ID on which you expect your application will be run. The linker sets the Subsystem version field in the .EXE header to the number you specify in the input box.

You can also set the Windows version ID in the SUBSYSTEM portion of the module definition file (.DEF file) However, any version setting you specify in the IDE or on the command line overrides the setting in the .DEF file.

Command-line usage

When you use the /Vd.d command-line option, the linker sets the Windows version ID to the number specified by d.d. For example, if you specify /V4.0, the linker sets the Subsystem version field in the .EXE header to 4.0, which indicates a Windows 95 application.

Default = 4.0


User version
User version (major.minor)

(Command-line switch = /Vd.d)

This option lets you specify the version ID of your executable. The linker sets the user version field in the .EXE header to the number you specify in the input box.

Command-line usage

When you use the /Ud.d command-line option, the linker sets the application version ID to the number specified by d.d. For example, if you specify /V4.0, the linker sets the user version field in the .EXE header to 4.0.

Default = 1.0


Image comment string

(Command-line switch = /GC)

The GC switch lets you add comment strings to the image.  These strings are inserted into the image directly after the object table in the PE file header. You can specify more than one string.

Command-line usage

ilink32 /GC"Here's the horse" /GC"Another animal" /GC"Goto!" c0x32 x,x.exe,,cw32mt import32,x,x xx

Default = OFF


Set image flags

(Command-line switch = /GF:xxxx)

The GF switch allows you to set several flags on the image.  The following

flags are supported:

-GF:SWAPNET

-GF:SWAPCD

-GF:UNIPROCESSOR

-GF:LARGEADDRESSAWARE

-GF:AGGRESSIVE

SWAPNET tells the OS to copy the image to a local swap file and run it from there if the image resides on a network drive.

SWAPCD tells the OS to copy the image to a local swap file and run it from there if the image resides on removable media (e.g. CD, floppy, zip drive).

UNIPROCESSOR tells the OS that this application cannot run on a multiprocessor system.

LARGEADDRESSAWARE tells the OS that the application understands addresses bigger than 4G.

AGGRESSIVE permits the OS to aggressively trim the working set of an application when the application is idle. This is ideal for screen savers, and other processes that wish to stay out of the way of main line processes as much as possible.

Default = OFF


Package linker options
Package options

See also

The following options apply to packages.

Build project as package

(Command-line switch = /Tpp)

The linker generates a package. This switch is included automatically in package makefiles.

Generate runtime-only package

(Command-line switch = /Gpr)

Generates a runtime-only package. (If neither /Gpr nor /Gpd is used, the resulting package works at both design time and runtime.)

Generate design-time-only package

(Command-line switch = /Gpd)

Generates a design-time-only package. (If neither /Gpr nor /Gpd is used, the resulting package works at both design time and runtime.)

Generate LIB file

(Command-line switch = /Gl)

Generates a .LIB file.


Set section flags

(Command-line switch = /GS)

The -GS switch lets you add flags to a named image section. The syntax is:

    -GS:string=[ECIRWSDKP]

This switch will add the flags to the existing flags for a given section. There is no way to remove default flags from a section.

Allowable flags are:

E - Executable

C - Contains Code

I - Contains initialized data

R - Section is readable

W - Section is writeable

S - Section is shared

D - Section is discardable

K - Section must not be cached

P - Section must not be paged

Command-line usage

-GS:.rsrc=W    Make the .rsrc section writeable


Replace resources

(Command-line switch = /Rr)

This option allows you to add and/or replace resources without stripping away the existing resources.


Calculate checksum

(Command-line switch = /Gz)

The /Gz option calculates the checksum of the target and places the result in the target’s PE header. This is used for NT Kernel mode drivers and system DLLs.

Default = OFF


Warning message options

See also

The Warning Message Options let you control the messages generated by the compiler. Messages are indicators of potential trouble spots in your program. These messages can warn you of many problems that may be waiting to happen, such as variables and parameters that are declared but never used, type mismatches, and many others.

Setting a message option causes the compiler to generate the associated message or warning when the specific condition arises. Note that some of the messages are on by default.

The different compiler messages can be broken in to the following subtopics

Portability

ANSI violations

Obsolete C++

Potential C++ errors

Inefficient C++ coding

Potential errors

Inefficient coding

General

User-defined warnings

Displaying warnings

Selecting warnings

Stop after n warnings

Stop after n errors


Portability message options

See also

Portability options enable or disable individual warning messages about statements that might not operate correctly in all computer environments.

Option	Command-line switch	Default

Non-portable pointer conversion	     -w-rpt	ON

Non-portable pointer comparison	     -w-cpt	ON

Constant out of range in comparison	     -w-rng	ON

Constant is long	     -wcln	OFF

Conversion may lose significant digits	     -wsig	OFF

Mixing pointers to signed and unsigned char	     -wucp	OFF


ANSI violation message options

See also

ANSI violations message options enable or disable individual warning messages about statements that violate the ANSI standard for the C language.

Option	Command-line switch	Default

Void functions may not return a value	     -w-voi	ON

Both return and return of a value used	     -w-ret	ON

Suspicious pointer conversion	     -w-sus	ON

Undefined structure 'ident'	     -wstu	OFF

Redefinition of 'ident' is not identical	     -w-dup	ON

Hexadecimal value more than three digits	     -w-big	ON

Bit fields must be signed or unsigned int	     -wbbf	OFF

'ident' declared as both external and static	     -w-ext	ON

Declare 'ident' prior to use in prototype	     -w-dpu	ON

Division by zero	     -w-zdi	ON

Initializing 'ident' with 'ident'	     -w-bei	ON

Initialization is only partially bracketed	     -wpin	OFF

Non-ANSI keyword used 	     -wnak	OFF


Obsolete C++ message options

See also

Obsolete C++ message options let you choose the obsolete items or incorrect syntax C++ warnings display.

Option	Command-line switch	Default

Base initialization without class name is obsolete	     -w-obi	ON

This style of function definition is obsolete	     -w-ofp	ON

Overloaded prefix operator used as a postfix operator	     -w-pre	ON


Potential C++ error message options

See also

Potential C++ errors message options enable or disable individual warning messages about statements that violate C++ language implementation.

Option	Command-line switch	Default

Constant member 'ident' is not initialized	     -w-nci	ON

Assigning 'type' to 'enumeration'	     -w-eas	ON

'function' hides virtual function 'function2'	     -w-hid	ON

Non-const function <function> called for const object	     -w-ncf	ON

Base class 'ident' inaccessible because also in 'ident'	     -w-ibc	ON

Array size for 'delete' ignored	     -w-dsz	ON

Use qualified name to access nested type 'ident'	     -w-nst	ON

Handler for '<type1>' Hidden by Previous Handler for '<type2>'	     -w-hch	ON

Conversion to 'type' will fail for virtual base members	     -w-mpc	ON

Maximum precision used for member pointer type <type>	     -w-mpd	ON

Use '> >' for nested templates instead of '>>'	     -w-ntd	ON

Non-volatile function <function> called for volatile object	     -w-nvf	ON


Inefficient C++ coding message options

See also

Inefficient C++ coding message options enable or disable individual warning messages about inefficient C++ coding.

Option	Command-line switch	Default

Functions containing 'ident' not expanded inline	     -w-inl	ON

Temporary used to initialize 'ident'	     -w-lin	ON

Temporary used for parameter 'ident'	     -w-lvc	ON


Potential error message options

See also

Potential error message options enable or disable individual warning messages about potential coding errors.

Option	Command-line switch	Default

Possibly incorrect assignment	     -w-pia	ON

Possible use of 'ident' before definition	     -wdef	OFF

No declaration for function 'ident'	     -wnod	OFF

Call to function with no prototype	     -w-pro	ON

Function should return a value	     -w-rvl	ON

Ambiguous operators need parentheses	     -wamb	OFF

Condition is always (true/false)	     -w-ccc	ON

Continuation character \ found in //	     -w-com	ON


Inefficient coding message options

See also

Inefficient coding message options are used to enable or disable individual warning messages about inefficient coding.

Option	Command-line switch	Default

'ident' assigned a value which is never used	     -w-aus	ON

Parameter 'ident' is never used	     -w-par	ON

'ident' declared but never used	     -wuse	OFF

Structure passed by value	     -wstv	OFF

Unreachable code	     -w-rch	ON

Code has no effect	     -w-eff	ON

The warnings Unreachable Code and Code Has No Effect can indicate serious coding problems. If the compiler generates these warnings, be sure to examine the lines of code that cause these warnings.


General message options

See also

General message options enable or disable a few general warning messages.

Option	Command-line switch	Default

Unknown assembler instruction	     -wasm	OFF

Ill-formed pragma	     -w-ill	ON

Array variable 'ident' is near	     -w-ias	ON

Superfluous & with function	     -wamp	OFF

'ident' is obsolete	     -w-obs	ON

Cannot create precompiled header	     -w-pch	ON

User-defined messages	     -w-msg	ON


User-defined warnings
User-defined messages

See also

(Command-line switch: -wmsg)

The user-defined messages option allows user-defined messages to appear in the IDE's Message window. User-defined messages are introduced with the #pragma message compiler syntax.

In addition to messages that you introduce with the #pragma message compiler syntax, User-defined messages displays messages introduced by third-party libraries. If you need Help concerning a message generated by third-party libraries, please contact the vendor of the header file that issued the message.

Default = ON


Display warnings
Display warnings options

See also

Use the Display Warnings options to choose which warnings are displayed by the compiler.

All

(Command-line switch: -w)

Display all warning and error messages.

Default = OFF

Selected

(Command-line switch: -wxxx)

Choose which warnings are displayed. xxx is the three-letter or four-digit message identifier used by the command-line option. Using pragma warn in your source code overrides messages options set either at the command line or in the IDE.

To disable a message from the command line, use the command-line option -w-xxx.

Default = Refer to the individual messages for their default status


Stop after n warnings

See also

(Command-line switch: -gn)

Warnings: Stop After causes compilation to stop after the specified number of warnings has been detected. You can enter any number from 0 to 255.

Entering 0 causes compilation to continue until either the end of the file or the error limit set in Stop after n errors has been reached, whichever comes first.

Default = 100


Stop batch compile after warnings

See also

(Command-line switch: -gb)

This option aborts batch compilations after the first file that causes warnings. For example,

BCC32 –c -gb *.ccp

BCC32 –c –gb file1.cpp file2.cpp

Without the –gb flag, batch compilations continue to the next scheduled file, even after an earlier file has caused a warning.

Default = OFF


Stop after n errors

See also

(Command-line switch: -jn)

Errors: Stop After causes compilation to stop after the specified number of errors has been detected. You can enter any number from 0 to 255.

Entering 0 causes compilation to continue until the end of the file or the warning limit set in Stop after n warnings has been reached, whichever comes first.

Default = 25


Stop batch compile after errors

See also

(Command-line switch: -jb)

This option aborts batch compilations after the first file that causes errors. For example,

BCC32 –c -gb *.ccp

BCC32 –c –gb file1.cpp file2.cpp

Without the –jb flag, batch compilations continue to the next scheduled file, even after an earlier file has caused a error.

Default = OFF


Aggregate optimization options

See also

Disable all optimizations

(Command-line switch: -Od)

Disables all optimization settings, including ones which you may have specifically set and those which would normally be performed as part of the speed/size tradeoff.

Because this disables code compaction (tail merging) and cross-jump optimizations, using this option can keep the debugger from jumping around or returning from a function without warning, which makes stepping through code easier to follow.

Optimize for size

(Command-line switches: -O1)

This switch sets an aggregate of optimization options that tells the compiler to optimize your code for size. For example, the compiler scans the generated code for duplicate sequences. When such sequences warrant, the optimizer replaces one sequence of code with a jump to the other and eliminates the first piece of code. This occurs most often with switch statements. The compiler optimizes for size by choosing the smallest code sequence possible.

Optimize for speed

(Command-line switch: -O2)

This switch sets an aggregate of optimization options that tells the compiler to optimize your code for speed.

Note:	Use of -G and -G- is deprecated.


Jump optimization option

See also

(Command-line switch: -O)

When Jump Optimization is set, the compiler reduces the code size by eliminating redundant jumps and reorganizing loops and switch statements.

When this option is set, the sequences of stepping in the debugger can be confusing because of the reordering and elimination of instructions. If you are debugging at the assembly level, you might want to disable this option.

Default = ON


Eliminate duplicate expressions option

See also

(Command-line switch: -Oc)

When this option is set, the compiler eliminates common subexpressions within groups of statements unbroken by jumps (basic blocks) and functions. This option globally eliminates duplicate expressions within the target scope and stores the calculated value of those expressions once (instead of recalculating the expression).

Although this optimization could theoretically reduce code size, it optimizes for speed and rarely results in size reductions. Use this option if you prefer to reuse expressions rather than create explicit stack locations for them.

The -Og compiler option is supported for backward compatibility only, and is equivalent to the -Oc compiler option.


Inline intrinsic functions option

See also

(Command-line switch: -Oi)

When Inline Intrinsic Functions is set, the compiler generates the code for common memory functions like strcpy() within your function's scope. This eliminates the need for a function call. The resulting code executes faster, but it is larger.

The following functions are inlined with this option:

alloca	fabs	memchr	memcmp

memcpy	memset	rotl	rotr

stpcpy	strcat	strchr	strcmp

strcpy	strlen	strncat	strncmp

strncpy	strnset	strrchr

You can control the inlining of these functions with the pragma intrinsic. For example, #pragma intrinsic strcpy causes the compiler to generate inline code for all subsequent calls to strcpy in your function, and #pragma intrinsic -strcpy prevents the compiler from inlining strcpy. Using these pragmas in a file overrides any compiler option settings.

When inlining any intrinsic function, you must include a prototype for that function before you use it; the compiler creates a macro that renames the inlined function to a function that the compiler recognizes internally. In the previous example, the compiler would create a macro #define strcpy __strcpy__.

The compiler recognizes calls to functions with two leading and two trailing underscores and tries to match the prototype of that function against its own internally stored prototype. If you don't supply a prototype, or if the prototype you supply doesn't match the compiler's prototype, the compiler rejects the attempt to inline that function and generates an error.


Induction variables option

See also

(Command-line switch: -Ov)

When this option is set, the compiler creates induction variables and it performs strength reduction, which optimizes for loops speed.

Use this option when you're compiling for speed and your code contains loops. The optimizer uses induction to create new variables (induction variables) from expressions used in loops. The optimizer assures that the operations performed on these new variables are computationally less expensive (reduced in strength) than those used by the original variables.

Optimizations are common if you use array indexing inside loops, because a multiplication operation is required to calculate the position in the array that is indicated by the index. For example, the optimizer creates an induction variable out of the operation v[i] in the following code because the v[i] operation requires multiplication. This optimization also eliminates the need to preserve the value of i:

int v[10];

void f(int x, int y, int z)

{

  int i;

  for (i = 0; i < 10; i++)

     v[i] = x * y * z;

}

With Induction variables set, the code changes:

int v[10];

void f(int x, int y, int z)

{

  int i, *p;

  for (p = v; p < &v[9]; p++)

    *p = x * y * z;

}


Pentium instruction scheduling option

See also

(Command-line switch: -OS)

When set, this switch rearranges instructions to minimize delays that can be caused by Address Generation Interlocks (AGI) which occur on the i486 and Pentium processors. This option also optimizes the code so that it takes advantage of the Pentium parallel pipelines. Best results for Pentium systems are obtained when you use this switch in conjunction with the Generate Pentium Instructions option (-5).

Scheduled code is more difficult to debug at the source level because instructions from a particular source line may be mixed with instructions from other source lines. Stepping through the source code is still possible, although the execution point might make unexpected jumps between source lines as you step. Also, setting a breakpoint on a source line may result in several breakpoints being set in the code. This is especially important to note when inspecting variables, since a variable may be undefined even though the execution point is positioned after the variable assignment.

Stepping through the following function when this switch is set demonstrates the stepping behavior:

int v[10];

void f(int i, int j)

{

int a,b;

a = v[i+j];

b = v[i-j];

v[i] = a + b;

v[j] = a - b;

}

Execution starts by computing the index i-j in the assignment to b (note that a is still undefined although the execution point is positioned after the assignment to a). The index i+j is computed, v[i-j] is assigned to b, and v[i+j] is assigned to a. If a breakpoint is set on the assignment to b, execution will stop twice: once when computing the index and again when performing the assignment.

Default = OFF (-O-S)