======================================================================= MICROSOFT (R) FOUNDATION CLASSES Version 4.2 Source Code ReadMe ======================================================================= This directory contains the source code to the MFC library. These files have been included for reference purposes, in conjunction with the Class Library Reference manual and tutorial. These files are compiled to form the Microsoft Foundation Classes 4.2 (MFC 4.2). The library may be built in a number of configurations, character sets (UNICODE or ANSI), and whether or not debugging and diagnostic aids are to be included in applications which link with the library. ============================================ 1. BUILDING A STATIC LINK LIBRARY VARIANT ============================================ The makefile provided can be used to build the static link library variants of MFC 4.2. See section 2 for instructions on building the shared DLL variant. The makefile can be used from either the MS-DOS command line (in a Windows NT cmd shell) or as an External Project file in the Microsoft Developer Studio. To build a library in a particular configuration, use the NMAKE tool and the makefile which is in this directory. The following arguments can be given to NMAKE to successfully build a specific library variant. NMAKE {DEBUG=[0|1]} {BROWSE=[0|1]} {BROWSEONLY={0|1} \ {CODEVIEW=[0|1|2]} {OBJ=path} \ {PLATFORM=INTEL|ALPHA|MIPS|PPC|M68K|MPPC} \ {UNICODE=[0|1]} \ {OPT=} Previous versions of MFC supported MODEL and TARGET options to control the memory model and to support DOS/CONSOLE mode targetting. These options are no longer supported (your Win32 console application can still be linked to the GUI MFC library, NAFXCW[D].LIB). For example to build default model with browser information in the debug build use the following settings: Debug Build: NMAKE DEBUG=1 CODEVIEW=1 BROWSE=1 Release Build: NMAKE DEBUG=0 DEBUG=[0|1] The "DEBUG" argument specifies whether or not to include diagnostic support code for the library. This may be 0 (for no diagnostics) or 1 (for full diagnostics). CODEVIEW=[0|1] The "CODEVIEW" argument specifies whether to compile the library with CodeView information or not. You need to compile the library with CodeView information if you want to trace into MFC code using the Visual C++ debugger. You should also compile your application files with the /Zi option, and link your executable with the /debug:full and /debugtype:cv options. Setting CODEVIEW does not affect the DEBUG argument, although the value of the DEBUG argument does affect the default value of CODEVIEW (discussed below). A value of 0 indicates that no CodeView information is to be compiled into the library. A value of 1 indicates to compile in full CodeView information for all modules of the library. The default value depends on the setting of the DEBUG argument. If DEBUG=1, CODEVIEW defaults to 1. If DEBUG=0, CODEVIEW defaults to 0. The installed libraries have been built with CODEVIEW=1 for maximum CodeView information. UNICODE=[0|1] The "UNICODE" argument specifies whether to create an MBCS or UNICODE aware library. If UNICODE is set to 1, the UNICODE variant of the specified library will be built. The default, UNICODE=0, specifies that an MBCS aware (or ANSI) library is to be built. OBJ=[path] We recommend storing .OBJ files in a separate directory so that you may compile different versions of the MFC library concurrently. The "OBJ" argument allows you to specify where these files are stored during the build process. The directory specified is created and removed automatically as required. This defaults to a combination of the target, model, and debug status, preceded by a '$' (i.e. $NWD). OPT=[switches] If your library needs to be built with custom compiler switches, then these may be included in the "OPT" argument. Note that switches need to be separated by spaces, so when including more than one extra compiler switch, enclose the whole OPT= argument in double-quotes. This is an advanced feature; read the makefile and the details on each of the switches concerned in the Microsoft C/C++ Compiler User Manual before using this option. Defaults The default is: nmake DEBUG=1 CODEVIEW=1 BROWSE=0 BROWSEONLY=0 UNICODE=0 OBJ=$NWD To set these options from MS Developer Studio, from the Build menu choose the Settings menu command and set them in the associated build sections. ============================= 2. BUILDING THE SHARED DLL ============================= Building the shared DLL is very similar to the static link variants. You must, however, use the MFCDLL.MAK which is also an External Project file. To build the shared DLL components that contain the implementation for OLE and ODBC use MFCOLE.MAK and MFCDB.MAK respectively. These additional DLLs are required only if your application utilizes the database or OLE classes. You must provide a unique name for your DLL(s) and you must provide a DEF file with a matching name. Typically, you can make a copy of the DEF files provided in the \msdev\mfc\src\ directory. Once you rename this DEF file to be the same base name as the DLL you're building you then need to add the additional exports (if any). Technical note TN033 explains in detail how to build the shared DLL and how to build an application that uses the shared DLL. =============================== 3. AFTER BUILDING THE LIBRARY =============================== Once the library has been built successfully, you may want to delete object files with: NMAKE CLEAN OBJ=[path] Note that if you used the "OBJ" argument while building the library, specify the same sub directory in the cleanup command. This will remove all of the temporary .OBJ files created by building the library, and remove the directory where they were stored. Always perform a cleanup before building a new variant of the library, or use different object paths for each variant. Note that the OBJ files are only necessary during the building process. =========================================== 4. BUILDING AND USING THE BROWSE DATABASE =========================================== A prebuilt MFC browser database is included on the Visual C++ CD-ROM. It is located in the same directory as the MFC source files, and can be accessed by opening :\MSDEV\MFC\SRC\MFC.BSC. You may want to build a browse database if you wish to merge the MFC browse information with your own project or you wish to build a different browse variant than the one provided (MFC.BSC is the browser database for NAFXCWD.LIB). The following instructions describe how to build the browse database using MFC's makefile and how to integrate the resulting .SBR files into your project. By building the library with either the BROWSE=1 or BROWSEONLY=1 options you can create the browse database files for the MFC source code. The output browse file (.BSC) will be placed in the source directory (this allows the browser to find the source files). The browse database files share a common naming convention with the libraries. Usually, it is sufficient to build only one browse database, although you can build a browse variant for each library variant that MFC supports. In addition, it is possible to build only the browse database, instead of building all the object files and library file. To build the NAFXCWD.BSC file, for example: NMAKE DEBUG=1 BROWSEONLY=1 The output will be placed in NAFXCWD.BSC (in the MFC source directory). In addition, all of the SBR files (the individual files, which when combined, form the .BSC) will be preserved in the OBJ directory (in this case $NWD). You can add these SBR files to your project's browse database, enabling you to browse the MFC source as well as your application source code at the same time. If you are using an external makefile, simply include the MFC SBRs in your BSCMAKE command. For example: BSCMAKE /o myproj.sbr myfile1.sbr myfile2.sbr \msdev\mfc\src\$nwd\*.sbr If you are using a Visual C++ project file, you can add it to your project settings. To do so, load your project (.MDP or .MAK) file: - From the Build menu, choose Settings to edit your project settings - Select the "Browse Info" tab in the settings dialog - Choose the target you wish to add the MFC browse information (ie. Win32 Debug or Win32 Retail) - Add the browse files (.SBR files) to "Project Options" edit box: \msdev\mfc\src\$nwd\*.sbr Note: Substitute the appropriate path if you built a different variant of the library or installed VC++ in a different directory than the default. Even if you are using the incremental build option of BSCMAKE (the default), these files will not be truncated to zero length (the files are marked in a special way to prevent the normal truncation that occurs when doing incremental builds). Note: The SBR files are protected from truncation by adding a special record (PCHMARK) that bscmake uses to protect SBR files that are refered to from pre-compiled header files (PCH). This record consists of a single byte with the value 0x10. The PCHMARK.BIN file contains this single byte -- it is appended to the SBR files during the build process. You can also open the resulting browse database file directly and use it to browse MFC source code. ====================================== 5. SOURCE CODE FORMATTING CONVENTION ====================================== All MFC source code has been formatted such that leading whitespace on a line is made up of physical tabs, while embedded whitespace is physical spaces. MFC source code assumes that your editor is set to display a physical tab as four blanks. For example: int FormatExample() { // Statements below should start in column 5 if tabs are set correctly // Comment should start in column 20 /* 0 1 2 12345678901234567890 */ int i; i = 5; // whitespace between statement and comment is spaces return i; } More information on MFC coding and commenting conventions can be found in Technical Note #46.