/Fo, /Fe, /Fs, /Fa, /Fl, /Fc, /Fm, /Fp, /Fr, /FR (Set Alternate Output Files)

Option

/Fofilename
/Fefilename
/Fs [[filename]]
/Fa [[filename]]
/Fl [[filename]]
/Fc [[filename]]
/Fm [[filename]]
/Fp [[filename]]
/Fr [[filename]]
/FR [[filename]]

Use these options to specify alternate names for output files. Table 13.3 summarizes the purpose of each option. This section begins with information that is true for all of the /F options and ends with information specific to each individual option.

Table 13.3 Optional File Types

Path Specifications and Extensions

If used, the filename argument must follow the option with no intervening space. It can be a file specification, a drive name, or a path specification. If filename is a drive name or path specification, the CL command creates the specified file or files in the given location; the default name is the base name of the first file plus the default extension. If the filename argument is a path without a filename (i.e., a directory), end the path with a backslash (\) or CL cannot differentiate the path from a filename.

You can give any name and extension you want for filename. If you give a filename without an extension, CL automatically appends the default extension.

Since you can process more than one file at a time with the CL command, the order in which you give listing options and the kind of argument you give for each option affect the result. Only one kind of object or assembly listing can be produced for each source file. The following list summarizes the effects of each option with each type of argument.

Interactions Between Options

The following list summarizes the interactions between the options.

DOS Device Names

You can append the MS-DOS device names AUX, CON, PRN, and NUL to the alternate output-file options and direct the resulting listing files to your terminal or printer. There can be no space between the option and the device name. For instance, the following command line generates assembler code for TEST.C and directs the output to the console:

CL /FaCON TEST.C

The following list summarizes the result when a device name is appended to an option:

Note:

Do not append a colon (:) to the device names when you use them as arguments to the listing options. For example, use CON instead of CON: and PRN instead of PRN:.

Examples

CL /FsHELLO.SRC /FcHELLO.CMB HELLO.CPP

In the first example, CL produces a source listing called HELLO.SRC and a combined source and assembly listing called HELLO.CMB. The object file has the default name HELLO.OBJ.

CL /FsHELLO.SRC /FsHELLO.LST /FcHELLO.CMB HELLO.CXX

The second example produces a source listing called HELLO.LST rather than HELLO.SRC, since the name associated with the rightmost option determines the resulting filename. This example also produces a combined source-code, assembler-code, and machine-code listing file called HELLO.CMB. The object file has the default name HELLO.OBJ.

CL /FsPRN HELLO.CXX

In this example, CL sends a source listing to the printer.

/Fo (Rename Object File)

Option

/Fofilename

By default, CL gives each object file it creates the base name of the corresponding source file plus the extension .OBJ. The /Fo option lets you give different names to object files or create them in a different directory. No space is allowed between the option and filename.

If you are compiling more than one source file, you can use the /Fo option with each source file to rename the corresponding object file. You can also use the /Fo option with a directory name to place all of the object files in a different directory. Note that the /Fo option requires a filename argument.

You can give any name and extension you want for filename. However, it is recommended that you use the conventional .OBJ extension since the linker and the LIB library manager use .OBJ as the default extension when processing object files.

Examples

CL /FoB:\OBJECT\ THIS.C

In this example, CL compiles the source file THIS.C and gives the resulting object file the name THIS.OBJ by default. The directory specification B: \OBJECT\ tells CL to create THIS.OBJ in the directory named \OBJECT on drive B.

CL /c /Fo\ASM\ THIS.C THAT.C /Fo\SRC\NEWTHOSE.OBJ THOSE.C

In this example, the /c option tells CL to run the compiler and not the linker. The first /Fo option tells the compiler to generate two object files, THIS.OBJ and THAT.OBJ, from THIS.C and THAT.C and place them in the \ASM directory. The second /Fo option tells the compiler to create the object file NEWTHOSE.OBJ (generated from THOSE.C) in the \SRC directory. Note that any path appended to an option must end with a backslash (\ASM must be \ASM\).

/Fe (Rename Executable File)

Option

/Fefilename

By default, CL names the executable file with the base name of the first file (source or object) on the command line plus the extension .EXE. The /Fe option lets you give the executable file a different name or create it in a different directory. Note that the /Fe option requires a filename argument.

Because CL creates only one executable file, you can type the /Fe option anywhere on the command line. If you enter more than one /Fe option, CL gives the executable file the name specified in the last /Fe option on the command line.

The /Fe option applies only in the linking stage. If you specify the /c option to suppress linking, /Fe has no effect.

Examples

CL /FeC:\BIN\PROCESS *.C

This example compiles and links all source files with the extension .C in the current directory. The resulting executable file is named PROCESS.EXE and is created in the directory C:\BIN.

CL /FeC:\BIN\ *.C

This example is similar to the first example except that the executable file is given the same base name as the first file compiled instead of being named PROCESS.EXE. The executable file is created in the directory C:\BIN.

/Fs (Create Source-File Listing)

Option

/Fs[[filename]]

The /Fs option produces a file that contains an annotated listing of the source file. This file lists and numbers every line in the source file, including lines of code, comment lines, and blank lines. The line numbers begin with 1. The file also lists the local and global symbols and classifies them by name, class, type, size, and off-set. If the symbol is a register variable, the file notes the register used. Finally, the file lists the size of the data segments and whether any errors were detected. You can use the /Sl, /Sp, /St, and /Ss options (described in this chapter) with the /Fs option to specify a source listing's line width and page length and to provide a title and subtitle.

Note that the /Fs option is not supported by the Fast Compile option (/f).

A fragment of a sample source-file listing follows:

.

.

.

83 if( result == NULL )

84 printf( " Value %u not found\n", key );

85 else

86 printf( " Value %u found in element %u\n",

87 key, result - array + 1 );

88 }

main Local Symbols

Name Class Type Size Offset Register

elements. . . . . . . . auto -0004

key . . . . . . . . . . auto -0002

i . . . . . . . . . . . auto *** si

result. . . . . . . . . auto *** di

.

.

.

cmpe Local Symbols

Name Class Type Size Offset Register

key . . . . . . . . . . param 0004

tableentry. . . . . . . param 0006

Global Symbols

Name Class Type Size Offset

array . . . . . . . . . common struct/array 2000 ***

bsearch . . . . . . . . extern near function *** ***

cmpe. . . . . . . . . . global near function *** 01cc

cmpgle. . . . . . . . . global near function *** 0196

lfind . . . . . . . . . extern near function *** ***

main. . . . . . . . . . global near function *** 0000

printf. . . . . . . . . extern near function *** ***

qsort . . . . . . . . . extern near function *** ***

rand. . . . . . . . . . extern near function *** ***

srand . . . . . . . . . extern near function *** ***

time. . . . . . . . . . extern near function *** ***

Code size = 01ee (494)

Data size = 011a (282)

Bss size = 0000 (0)

No errors detected

Examples

CL /FsQSORT QSORT.C

This example compiles and links the source file QSORT.C and generates a source-listing file named QSORT.LST.

/Fa (Create Assembly-File Listing)

Option

/Fa[[filename]]

The /Fa option translates your C or C++ source code to assembly language. Unless you name the resulting file with the optional filename argument, it is given the base name of the C or C++ source file specified on the CL command line with an .ASM extension.

A fragment of a sample assembly-language listing follows:

.

.

.

_mainPROC NEAR

; Line 28

pushbp

movbp,sp

movax,8

call__aNchkstk

;i = -4

;result = -8

;elements = -2

;key = -6

; Line 29

movWORD PTR [bp-2],1000;elements

movWORD PTR [bp-6],500;key

; Line 32

xorax,ax

pushax

call_time

addsp,2

pushax

call_srand

addsp,2

; Line 35

movax,OFFSET DGROUP:$SG330

pushax

call_printf

addsp,2

; Line 36

movWORD PTR [bp-4],0;i

$FC332:

; Line 37

call_rand

movcx,1000

cwd

idivcx

incdx

movbx,WORD PTR [bp-4];i

shlbx,1

movWORD PTR _array[bx],dx

incWORD PTR [bp-4];i

cmpWORD PTR [bp-4],cx;i

jb$FC332

.

.

.

Example

CL /FaQSORT QSORT.C

This example compiles and links the source file QSORT.C and generates an assembly-listing file named QSORT.ASM.

/Fl (Combined Assembly- and Machine-Code Listing)

Option

/Fl[[filename]]

The /Fl option translates your C or C++ source code to a combined assembly-and machine-code listing. Unless you name the resulting file with the optional filename argument, it is given the base name of the C or C++ source file specified on the CL command line with a .COD extension.

A fragment of a sample assembly- and machine-code listing follows:

.

.

.

_mainPROC NEAR

; Line 28

*** 00000055 pushbp

*** 0000018b ec movbp,sp

*** 000003b8 08 00 movax,8

*** 000006e8 00 00 call__aNchkstk

;i = -4

;result = -8

;elements = -2

;key = -6

; Line 29

*** 000009c7 46 fe e8 03 movWORD PTR [bp-2],1000;elements

*** 00000ec7 46 fa f4 01 movWORD PTR [bp-6],500;key

; Line 32

*** 00001333 c0 xorax,ax

*** 00001550 pushax

*** 000016e8 00 00 call_time

*** 00001983 c4 02 addsp,2

*** 00001c50 pushax

*** 00001de8 00 00 call_srand

*** 00002083 c4 02 addsp,2

; Line 35

*** 000023b8 00 00 movax,OFFSET DGROUP:$SG330

*** 00002650 pushax

*** 000027e8 00 00 call_printf

*** 00002a83 c4 02 addsp,2

; Line 36

*** 00002dc7 46 fc 00 00 movWORD PTR [bp-4],0;i

$FC332:

; Line 37

*** 000032e8 00 00 call_rand

*** 000035b9 e8 03 movcx,1000

*** 00003899 cwd

*** 000039f7 f9 idivcx

*** 00003b42 incdx

*** 00003c8b 5e fc movbx,WORD PTR [bp-4];i

*** 00003fd1 e3 shlbx,1

*** 00004189 97 00 00 movWORD PTR _array[bx],dx

*** 000045ff 46 fc incWORD PTR [bp-4];i

*** 00004839 4e fc cmpWORD PTR [bp-4],cx;i

*** 00004b72 e5 jb$FC332

.

.

.

/Fc (Combined Source-, Assembly-, and Machine-Code Listing)

Option

/Fc[[filename]]

The /Fc option translates your C or C++ source code to a combined source-code, assembly-code, and machine-code listing. The file numbers and lists every line contained in your C or C++ source file and follows each line of source code with the code the compiler generates. Unless you name the resulting file with the optional filename argument, it is given the base name of the C or C++ source file specified on the CL command line with a .COD extension.

Following is a fragment of a combined source-code, assembly-code, and machine-code listing:

.

.

.

_mainPROC NEAR

;|*** /* QSORT.C illustrates randomizing, sorting, and searching. Functions

;|*** * illustrated include:

;|*** * srand rand qsort

;|*** * _lfind _lsearch bsearch

;|*** *

;|*** * The _lsearch function is not specifically shown in the program, but

;|*** * its use is the same as _lfind except that, if it does not find the

;|*** * element, it inserts it at the end of the array rather than failing.

;|*** */

;|***

;|*** #include <search.h>

;|*** #include <stdlib.h>

;|*** #include <string.h>

;|*** #include <stdio.h>

;|*** #include <time.h>

;|***

;|*** #define ASIZE 1000

;|*** unsigned array[ASIZE];

;|***

;|*** /* Macro to get a random integer within a specified range */

;|*** #define getrandom( min, max ) ((rand() % (int)(((max)+1) - (min))) + (min))

;|***

;|*** /* Must be declared before call */

;|*** int __cdecl cmpgle( unsigned *elem1, unsigned *elem2 );

;|*** int __cdecl cmpe( unsigned *key, unsigned *tableentry );

;|***

;|*** void main()

;|*** {

; Line 28

*** 00000055 pushbp

*** 0000018b ec movbp,sp

*** 000003b8 08 00 movax,8

*** 000006e8 00 00 call__aNchkstk

;i = -4

;result = -8

;elements = -2

;key = -6

;|*** unsigned i, *result, elements = ASIZE, key = ASIZE / 2;

; Line 29

*** 000009c7 46 fe e8 03 movWORD PTR [bp-2],1000;elements

*** 00000ec7 46 fa f4 01 movWORD PTR [bp-6],500;key

;|***

;|*** /* Seed the random number generator with current time. */

;|*** srand( (unsigned)time( NULL ) );

; Line 32

*** 00001333 c0 xorax,ax

*** 00001550 pushax

*** 000016e8 00 00 call_time

*** 00001983 c4 02 addsp,2

*** 00001c50 pushax

*** 00001de8 00 00 call_srand

*** 00002083 c4 02 addsp,2

.

.

.

Example

CL /FcQSORT QSORT.C

This example compiles and links the source file QSORT.C and also generates a combined source-code, assembly-code, and machine-code listing file named QSORT.COD.

/Fm (Create Map File)

Option

/Fm[[filename]]

The /Fm option produces a map file. The map file contains a list of segments in order of their appearance within the load module.

A fragment of a sample map file follows:

Start Stop Length Name Class

00000H 01E9FH 01EA0H _TEXT CODE

01EA0H 01EA0H 00000H C_ETEXT ENDCODE

.

.

.

The information in the Start and Stop columns shows the 20-bit address (in hexadecimal) of each segment, relative to the beginning of the load module. The load module begins at location zero. The Length column gives the length of the segment in bytes. The Name column gives the name of the segment, and the Class column gives information about the segment type. The starting address and name of each group appear after the list of segments. A sample group listing follows:

Origin Group

01EA:0 DGROUP

In this example, DGROUP is the name of the data group. DGROUP is used for all near data (that is, all data not explicitly or implicitly placed in their own data segment) in Microsoft C/C++ programs.

The following map file contains two lists of global symbols: the first list is sorted in ASCII-character order by symbol name, and the second is sorted by symbol address. The notation Abs appears next to the names of absolute symbols ( symbols containing 16-bit constant values that are not associated with program addresses).

Address Publics by Name

01EA:0096 STKHQQ

0000:1D86 _brkctl

01EA:04B0 _edata

01EA:0910 _end

.

.

.

01EA:00EC __abrkp

01EA:009C __abrktb

01EA:00EC __abrktbe

0000:9876 Abs __acrtmsg

0000:9876 Abs __acrtused

.

.

.

01EA:0240 ___argc

01EA:0242 ___argv

Address Publics by Value

0000:0010 _main

0000:0047 _htoi

0000:00DA _exp16

0000:0113 __chkstk

0000:0129 __astart

0000:01C5 __cintDIV

.

.

.

Global symbols in a map file usually have one or more leading underscores because the compiler adds an underscore to the beginning of variable names. Many of the global symbols that appear in the map file are symbols used internally by the compiler and the standard libraries.

The addresses of the external symbols show the location of the symbol relative to zero (the beginning of the load module).

Following the lists of symbols, the map file gives the program entry point, as shown in the following example:

Program entry point at 0000:0129

/Fp (Specify Precompiled Header Filename)

Option

/FPfilename

Option (/Fp)

Use the /Fp option to specify the name of the desired .PCH file in cases where the .PCH filename specified with the /Yc option is different than the filename of the associated include file or source file. For example, if you want to create a precompiled header file for a debugging version of your program, you can specify a command such as:

CL /DDEBUG /YcPROG /FcDPROG PROG.CPP

This command creates a precompilation of all header files up to and including PROG.H, and stores it in a file called DPROG.PCH. If you need a release version in parallel, change the compilation command to:

CL /YcPROG /FpRPROG PROG.CPP

This command creates a separate precompilation of the header files up to and including PROG.H and stores it in RPROG.PCH.

For more information on precompiled headers, see Chapter 2 in the Programming Techniques manual. The related options /Yc, /Yd, and /Yu are described later in this chapter.

/FR, /Fr (Generate PWB Browser Files from CL)

Option

/FR[[filename]]

/Fr[[filename]]

These options are part of the process you must follow to use the PWB Source Browser. Both options create a file with an .SBR extension; only one option is required. The BSCMAKE utility uses an .SBR file to generate a database file with a .BSC extension. This is the file used by the Source Browser.

An .SBR file contains symbolic information about your program. The /FR option generates complete symbolic information in the .SBR file. The /Fr option generates symbolic information without information on local variables. Both /FR and /Fr use the SBRPACK utility to compact the .SBR file by removing unreferenced definitions. As the BSCMAKE utility uses .SBR files to produce output for the PWB Source Browser, a smaller .SBR file gives BSCMAKE greater effective capacity and can also increase the speed of producing .BSC files. Smaller .SBR files save disk space.

By default, both options generate a filename that uses the source file's base name and appends an .SBR extension. Use the filename argument to provide a name other than the default; an .SBR extension is required. No space is allowed between either the /FR or the /Fr option and the filename argument.

The /Zn option, described later in this chapter, suppresses the CL driver's call to SBRPACK. The /Zn option is required if you want to use BSCMAKE's /Iu option.

For information about using the PWB Source Browser to look for code in a project, to see where functions are invoked or where variables and types are used, or to generate call trees and cross-reference tables, see Chapter 21, “Browser Utilities.”

Example

CL /FRNEWSORT QSORT.C

This example compiles and links the source file QSORT.C and generates a file named NEWSORT.SBR. The SBRPACK utility then compacts the .SBR file, and the BSCMAKE utility uses it to generate a .BSC file that you can examine with the PWB Source Browser.