Q98656: INFO: Creating a Browser Library for the Foundation Classes
Article: Q98656
Product(s): Microsoft C Compiler
Version(s): winnt:1.0,4.0
Operating System(s):
Keyword(s): kbnokeyword kbCompiler kbMFC kbMiscTools kbVC kbVC100 kbVC150 kbVC400
Last Modified: 07-MAY-2001
-------------------------------------------------------------------------------
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:
1. 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
2. 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:
1. 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.
2. 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:
1. 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.
2. 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.
1. 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.
2. 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.
a. Choose Project from the Options menu.
b. Choose Compiler in the Customize Build Options group.
c. Choose Listing Files in the Category group.
d. Clear the Browser Information check box.
e. Choose Custom Options in the Category group.
f. At the beginning of the Other Options field enter "/Fr.\" (without the
quotation marks).
g. 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.)
3. In Visual Workbench, add an option on the Tools menu to call BSCMAKE, as
follows:
a. Choose Tools from the Options menu.
b. Choose Add.
c. 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).
d. Modify the contents of the Menu Text field to read something like "BSCMAKE
with MAFXCWD" (without the quotation marks).
e. 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.
f. 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
Technology : kbAudDeveloper kbMFC
Version : winnt:1.0,4.0
Issue type : kbinfo
=============================================================================
THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.
Copyright Microsoft Corporation 1986-2002.