INFO: Creating a Browser Library for the Foundation Classes

ID: Q98656

The information in this article applies to:

The Microsoft Foundation Classes (MFC), used with:
- Microsoft Visual C++ for Windows, 16-bit edition, versions 1.0, 1.5, 1.51, 1.52
- Microsoft Visual C++, 32-bit Editions, versions 1.0, 4.0

SUMMARY

The Microsoft Visual C++ products include the source code for the Microsoft Foundation Class (MFC) Library. Because it is important to understand the implementation of the Foundation Classes when overriding or using member functions, developers are encouraged to construct a Browser database for the Microsoft Foundation Classes source code. Once a Browser database (.BSC file) is created, it can be loaded into the Visual Workbench by choosing File.Open.

This article discusses the following:

Modifying the MFC source makefile to create a Browser database without re-building the Foundation Classes Library.

Modifying the MFC source makefile to create a Browser database while re-building the library.

Integrating the Foundation Classes Browser information into your project.

For more information about the Browser tool, see chapter 7 in the Visual Workbench User's Guide.

NOTE: The distribution CD for Microsoft Visual C++ 32-bit Edition, versions 2.x and 4.0, contains a pre-built browser database for the 32-bit edition of MFC, versions 3.x and 4.0, respectively. This browser database can be found in the MFC source code directory as \MSVC20\MFC\SRC\MFC.BSC for Visual C++ 2.x and as \MSDEV\MFC\SRC\MFC.BSC for Visual C++ 4.0. Although Visual C++ 1.5x is included on the Visual C++ 2.x CD, this CD does not contain a pre-built browser database for the 16-bit version of MFC. Nevertheless, one can be built following the instructions below.

MORE INFORMATION

Modifying the 'makefile' File to Add Rules for Building the .bsc File

Make the following additions to the file called MAKEFILE in the \MSVC\MFC\SRC directory:

You'll see the lines:


      ###############################################################
      # Set CPPFLAGS for use with .cpp.obj and .c.obj rules
      # Define rule for use with OBJ directory
      # C++ uses a PCH file

On the next line after this, include the text:


      # define compiler options for building just the .BSC file
      # BSC=1 means browser database only
      # BSC=2 means browser database with library rebuild
      !if "$(BSC)"=="1"
      OPT=$(OPT) /FR$D\ /Zn /Zs
      !else if "$(BSC)"=="2"
      OPT=$(OPT) /FR$D\ /Zn
      !endif

You also see the lines:


      ###############################################################
      # Goals to build

      goal: create.dir ..\lib\$(GOAL).lib

Change this to:


      ##############################################################
      # Goals to build

      !if "$(BSC)"!="1"
      goal: create.dir ..\lib\$(GOAL).lib bsc
      !endif

      !if "$(BSC)"=="1" || "$(BSC)"=="2"
      #Build .BSC file
      bsc: create.dir $(OBJS)
         cd $D
         bscmake /Iu /o $(GOAL).bsc *.sbr
         del *.sbr

      !else
      bsc:

      !endif

These changes will allow you to use the MAKEFILE NMAKE file to create a Browser database for the Microsoft Foundation Classes. You will run the makefile the same as that which is described in the README.TXT file located in the \MSVC\MFC\SRC directory. The only difference is that you can specify whether you want a .BSC file created for the project. Be sure that you understand the information in the README.TXT file before reading further.

See NMAKE.WRI in the \MSVC\MFC\HELP directory for more information about using NMAKE and creating NMAKE files.

Creating a Browser Database without Re-building OBJs or the Library

After you have made the modifications to the MAKEFILE file described above, perform the following steps to create the Browser file (.BSC file) for the Foundation Class Library:

If you have previously built the library and OBJs already exist in the destination directory (i.e. $MWD), delete the .PCH and OBJs in that directory. You can do this by following the directions in section 3 for the \MSVC\MFC\SRC\README.TXT file.

Make sure you have you have the system environment variables configured correctly (by running MSVCVARS.BAT or VCVARS32.BAT) and invoke the NMAKE command line specifying "BSC=1". "BSC=1" means that just the browser database (.BSC) will be built. The OBJs and Library will not be built. Here is an example of a command line you might specify:
```
      NMAKE MODEL=M TARGET=W DEBUG=1 DLL=0 BSC=1 
```
This will build a file called MAFXCWD.BSC in the $MWD subdirectory under the \MSVC\MFC\SRC directory. See the \MSVC\MFC\SRC\README.TXT file for more information about the NMAKE parameters shown above.

To use the Browser file, start VC++ and select "Open" from the file menu. Choose the .BSC file which you created. The Browser window will appear and you can then look up any of the MFC functions or data variables.

You may want to delete the .PCH file that is located in the same directory as the .BSC file you created.

Creating a Browser Database when Re-building the Library

To create a .BSC file for the Foundation Classes when rebuilding the MFC library, first you must make the modifications shown above to the MAKEFILE file. Next, perform the following steps:

If you have previously built the library and OBJS already exist in the destination directory (i.e. $MWD), delete the .PCH and OBJs in that directory. You can do this by following the directions in section 3 for the \MSVC\MFC\SRC\README.TXT file.

Make sure you have you have the system environment variables configured correctly (by running MSVCVARS.BAT or VCVARS32.BAT) and invoke the NMAKE command line specifying "BSC=2". The OBJs and Library will not be built. Here is an example of a command line you might specify:
```
      NMAKE MODEL=M TARGET=W DEBUG=1 DLL=0 CODEVIEW=1 BSC=2 
```
This NMAKE command line will build the medium model, Windows, debug, MFC library and place it in the $MWD subdirectory. It will also build a Browser database for the library. The file will be called MAFXCWD.BSC.

See the \MSVC\MFC\SRC\README.TXT file for more information about the NMAKE parameters shown above.

To use the Browser file, start Visual C++ and select "Open" from the file menu. Choose the .BSC file which you created. The Browser window will appear and you can then look up any of the MFC functions or data variables.

Integrating the Class Library Browser Information into Your Project

The text below presents the three steps required to integrate the MFC Library browser information (.SBR files) into your project browser database.

Create browser information files (.SBR) for the appropriate MFC library.

To create the SBR files, follow the directions above except don't add the makefile line "del *.sbr". Also, place a "/n" on the BSCMAKE command line. This will prevent the .SBR files from getting truncated to zero when the .BSC file is created. After building the browser database for the MFC library, you will be left with .SBR files as well.

Load your project in Visual C++ and modify the compiler options as follows to place the .SBR files for your project into the current directory.
1. Choose Project from the Options menu.
2. Choose Compiler in the Customize Build Options group.
3. Choose Listing Files in the Category group.
4. Clear the Browser Information check box.
5. Choose Custom Options in the Category group.
6. At the beginning of the Other Options field enter "/Fr.\" (without the quotation marks).
7. Choose OK.
(You must disable browser information for your project to prevent Visual C++ from calling BSCMAKE. If Visual C++ calls BSCMAKE, the browser database includes only .SBR files for files in the project; the MFC Library files are not included.)

In Visual Workbench, add an option on the Tools menu to call BSCMAKE, as follows:
1. Choose Tools from the Options menu.
2. Choose Add.
3. In the Add Tool dialog box, specify the path to BSCMAKE in the File Name field (by default C:\MSVC\BIN\BSCMAKE under Windows and C:\MSVCNT\BIN\BSCMAKE under Windows NT).
4. Modify the contents of the Menu Text field to read something like "BSCMAKE with MAFXCWD" (without the quotation marks).
5. Specify the the following in the Arguments field:
```
         /o$PROJ /n *.SBR <sbrdirectory>\*.sbr 
```
  where <sbrdirectory> is the directory where the SBR files are located. For example, if you followed the directions in step 1 and created the .SBR files for the medium model, debug, Windows, MFC library, you're SBR files will be located in the \MSVC\MFC\SRC\$MWD.
6. Choose OK.
NOTE: The BSCMAKE command line includes the /n option switch. As the documentation describes, this switch prevents BSCMAKE from performing an incremental build that truncates all .SBR files to zero bytes. The /n option slows the .BSC build; however, it preserves the .SBR files for other projects to use. To speed performance, you may want to make a backup copy of the MFC Library .SBR files for repeated use and edit the Arguments field to remove the /n option switch to enable incremental builds.

You may want to modify the Arguments field to include the /Iu option switch. The /Iu switch instructs BSCMAKE to include all information that the source code defines but does not reference. By default, BSCMAKE does not include any symbols that are not referenced. Unfortunately, if you specify the /Zn compiler option in the Visual Workbench, VWB sets the Browser Information check box (and invokes BSCMAKE without specifying the MFC Library .SBR files). In Visual C++ version 1.0, the ability to browse MFC Library files and to browse symbols that are defined but not referenced are mutually exclusive.

To build the .BSC file for your project, build the project, then run BSCMAKE from the newly created option on the Tools menu.

IMPORTANT: You must close the browser window before you run BSCMAKE. BSCMAKE cannot create a new browser file unless the .BSC file is closed.

Important Notes

If you are running Windows with the Win32s DLLs, you will not be able to run BSCMAKE from the Tools menu. You must run it from the MS-DOS command line.

The .BSC file you create must not be moved to another directory otherwise the browser will not be able to find the source files.

Do not specify /A on the NMAKE command line if you don't have Microsoft Macro Assembler 6.1 or greater in your PATH. The /A option will do a "rebuild all" and will cause some assembler files (.ASM files) to be re-assembled. Of course, if you don't have the assembler, the makefile will fail.

For more information about BSCMAKE, view the BSCMAKE.WRI file located in the MSVC\HELP directory.

For more information about NMAKE, view the NMAKE.WRI file located in the MSVC\HELP directory.

Additional query words:

Keywords : kbnokeyword kbCompiler kbMFC kbMiscTools kbVC kbVC100 kbVC150 kbVC400
Version : winnt:1.0,4.0
Platform : winnt
Issue type : kbinfo