PRB: Unreferenced Symbols Don't Appear in .BSC File

WINDOWS        | WINDOWS NT

The information in this article applies to:

  - Microsoft Visual C++ for Windows, versions 1.0, 1.5, and 1.51
  - Microsoft Visual C++, 32-bit Edition, version 1.0

SYMPTOMS

Unless a symbol is referenced in a program, it will not appear in the browser database.

CAUSE

This problem is due to the default behaviors of the Compiler (CL.EXE) and how it handles browser files (.SBR files), as well as the Browser Database Maintenance Utility (BSCMAKE.EXE) and how it handles browser databases (.BSC files).

NOTE: This article does not apply to Microsoft Visual C++, 32-bit Edition, version 2.0 and above. In these versions, when the compiler option "Don't Pack Info" is selected, the option /Zn is added to the CL compile line. Subsequently, the option /Iu is automatically added to BSCMAKE.EXE.

RESOLUTION

By understanding the default behaviors, you can discover where unreferenced symbols are defined. The default behavior of the Compiler when using the /FR or /Fr switches is to pack browser files, removing information about where unreferenced symbols are defined. To prevent the Compiler from doing this packing, use the /Zn switch from the command line, or check the "Don't Pack Information" checkbox under:

   Options...|Project...|Compiler...|Listing Files

NOTE: There is no way to control BSCMAKE's behavior when using a Visual Workbench-generated makefile. The hard-coded default BSCMAKE command line used by the Visual Workbench doesn't include the /Iu option. In the case of a Visual Workbench-generated makefile, find the inference rule within the makefile generated by the Visual Workbench that causes the BSCMAKE utility to be executed. There, change the command line that is passed to the BSCMAKE utility. To do this, open the makefile as a text file and find the $(PROJ).BSC: inference rule. You should see the BSCMAKE command on the next line or two. Just add the /Iu option as shown in this example:

$(PROJ).BSC: $(SBRS)

    bscmake@<<

NOTE: There is an important caveat here. When you use the internal build engine of the Visual Workbench, the inference rule portion of the makefile is not used. Instead, the Visual Workbench uses the inference rules only when the file is opened as an external makefile. For this solution to work, the makefile must be opened as an external makefile in the Visual Workbench or the project must be built with NMAKE from the command line.

NOTE: The Compiler and BSCMAKE work independently. BSCMAKE builds the browser database from browser (.SBR) files generated at compile time. Unreferenced symbols will not appear in the browser database if:

• CL.EXE is executed with /Fr or /FR, and without the /Zn option, regardless of whether BSCMAKE is executed with the /Iu option. Omitting the /Zn option causes browser file packing to discard information about unreferenced symbols.
• CL.EXE is executed with /Fr or /FR, and /Zn, and BSCMAKE is executed without the /Iu option. Omitting the /Iu option causes BSCMAKE to ignore information about unreferenced symbols.

• The Compiler must be executed with /Fr or /FR, and /Zn.
• BSCMAKE must be executed with the /Iu option in the same build.

MORE INFORMATION

An unreferenced symbol is a symbol that has been defined, but never appears in the body of code apart from its definition. Common examples of defined but unreferenced symbols are instances of CWinApp-derived classes in MFC applications and variables of any type that are not used in an application.