home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / mfc / src / readme.txt < prev    next >
Text File  |  1998-06-16  |  10KB  |  243 lines
  1. =======================================================================
  2.                      MICROSOFT (R) FOUNDATION CLASSES
  3.                               Version 4.2
  4.                            Source Code ReadMe
  5. =======================================================================
  6.  
  7. This directory contains the source code to the MFC library.
  8.  
  9. These files have been included for reference purposes, in
  10. conjunction with the Class Library Reference manual and tutorial.
  11.  
  12. These files are compiled to form the Microsoft Foundation Classes 4.2
  13. (MFC 4.2).  The library may be built in a number of configurations,
  14. character sets (UNICODE or ANSI), and whether or not debugging and
  15. diagnostic aids are to be included in applications which link with
  16. the library.
  17.  
  18. ============================================
  19.  1.  BUILDING A STATIC LINK LIBRARY VARIANT
  20. ============================================
  21.  
  22. The makefile provided can be used to build the static link library
  23. variants of MFC 4.2.  See section 2 for instructions on building
  24. the shared DLL variant.  The makefile can be used from either the
  25. MS-DOS command line (in a Windows NT cmd shell) or as an External
  26. Project file in the Microsoft Developer Studio.
  27.  
  28. To build a library in a particular configuration, use the NMAKE tool
  29. and the makefile which is in this directory.  The following arguments
  30. can be given to NMAKE to successfully build a specific library variant.
  31.  
  32.   NMAKE {DEBUG=[0|1]} {BROWSE=[0|1]} {BROWSEONLY={0|1} \
  33.         {CODEVIEW=[0|1|2]} {OBJ=path} \
  34.         {PLATFORM=INTEL|ALPHA|MIPS|PPC|M68K|MPPC} \
  35.         {UNICODE=[0|1]} \
  36.         {OPT=<CL command line switches>}
  37.  
  38. Previous versions of MFC supported MODEL and TARGET options to control the
  39. memory model and to support DOS/CONSOLE mode targetting. These options are
  40. no longer supported (your Win32 console application can still be linked to
  41. the GUI MFC library, NAFXCW[D].LIB).
  42.  
  43. For example to build default model with browser information in the debug
  44. build use the following settings:
  45.  
  46.     Debug Build:  NMAKE DEBUG=1 CODEVIEW=1 BROWSE=1
  47.     Release Build: NMAKE DEBUG=0
  48.  
  49. DEBUG=[0|1]
  50.     The "DEBUG" argument specifies whether or not to include diagnostic
  51.     support code for the library.  This may be 0 (for no diagnostics)
  52.     or 1 (for full diagnostics).
  53.  
  54. CODEVIEW=[0|1]
  55.     The "CODEVIEW" argument specifies whether to compile the library with
  56.     CodeView information or not.  You need to compile the library with
  57.     CodeView information if you want to trace into MFC code using the
  58.     Visual C++ debugger.    You should also compile your application files
  59.     with the /Zi option, and link your executable with the /debug:full
  60.     and /debugtype:cv options.
  61.  
  62.     Setting CODEVIEW does not affect the DEBUG argument, although the
  63.     value of the DEBUG argument does affect the default value of CODEVIEW
  64.     (discussed below).  A value of 0 indicates that no CodeView
  65.     information is to be compiled into the library.  A value of 1 indicates
  66.     to compile in full CodeView information for all modules of the library.
  67.  
  68.     The default value depends on the setting of the DEBUG argument.
  69.     If DEBUG=1, CODEVIEW defaults to 1.  If DEBUG=0, CODEVIEW defaults
  70.     to 0.  The installed libraries have been built with CODEVIEW=1 for
  71.     maximum CodeView information.
  72.  
  73. UNICODE=[0|1]
  74.     The "UNICODE" argument specifies whether to create an MBCS
  75.     or UNICODE aware library.  If UNICODE is set to 1, the UNICODE
  76.     variant of the specified library will be built.  The default,
  77.     UNICODE=0, specifies that an MBCS aware (or ANSI) library is
  78.     to be built.
  79.  
  80. OBJ=[path]
  81.     We recommend storing .OBJ files in a separate directory so that you
  82.     may compile different versions of the MFC library concurrently.
  83.     The "OBJ" argument allows you to specify where these files are stored
  84.     during the build process.  The directory specified is created and
  85.     removed automatically as required.  This defaults to a combination
  86.     of the target, model, and debug status, preceded by a '$' (i.e. $NWD).
  87.  
  88. OPT=[switches]
  89.     If your library needs to be built with custom compiler switches, then
  90.     these may be included in the "OPT" argument.  Note that switches need
  91.     to be separated by spaces, so when including more than one extra
  92.     compiler switch, enclose the whole OPT= argument in double-quotes.
  93.     This is an advanced feature; read the makefile and the details on each
  94.     of the switches concerned in the Microsoft C/C++ Compiler User Manual
  95.     before using this option.
  96.  
  97. Defaults
  98.     The default is:
  99.     nmake DEBUG=1 CODEVIEW=1 BROWSE=0 BROWSEONLY=0 UNICODE=0 OBJ=$NWD
  100.  
  101. To set these options from MS Developer Studio, from the Build menu choose
  102. the Settings menu command and set them in the associated build sections.
  103.  
  104. =============================
  105.  2.  BUILDING THE SHARED DLL
  106. =============================
  107.  
  108. Building the shared DLL is very similar to the static link variants.  You
  109. must, however, use the MFCDLL.MAK which is also an External Project file.
  110.  
  111. To build the shared DLL components that contain the implementation for
  112. OLE and ODBC use MFCOLE.MAK and MFCDB.MAK respectively. These additional
  113. DLLs are required only if your application utilizes the database or
  114. OLE classes.
  115.  
  116. You must provide a unique name for your DLL(s) and you must provide a DEF
  117. file with a matching name.  Typically, you can make a copy of the DEF
  118. files provided in the \msdev\mfc\src\<platform> directory.
  119.  
  120. Once you rename this DEF file to be the same base name as the DLL you're
  121. building you then need to add the additional exports (if any).
  122.  
  123. Technical note TN033 explains in detail how to build the shared DLL and
  124. how to build an application that uses the shared DLL.
  125.  
  126.  
  127. ===============================
  128.  3. AFTER BUILDING THE LIBRARY
  129. ===============================
  130.  
  131. Once the library has been built successfully, you may want to delete object
  132. files with:
  133.  
  134.     NMAKE CLEAN OBJ=[path]
  135.  
  136. Note that if you used the "OBJ" argument while building the library, specify
  137. the same sub directory in the cleanup command.
  138.  
  139. This will remove all of the temporary .OBJ files created by building the
  140. library, and remove the directory where they were stored.
  141.  
  142. Always perform a cleanup before building a new variant of the library,
  143. or use different object paths for each variant.  Note that the OBJ files
  144. are only necessary during the building process.
  145.  
  146.  
  147. ===========================================
  148.  4. BUILDING AND USING THE BROWSE DATABASE
  149. ===========================================
  150.  
  151. A prebuilt MFC browser database is included on the Visual C++ CD-ROM.
  152. It is located in the same directory as the MFC source files, and can be
  153. accessed by opening <cd-drive>:\MSDEV\MFC\SRC\MFC.BSC.  You may want to
  154. build a browse database if you wish to merge the MFC browse information
  155. with your own project or you wish to build a different browse variant than
  156. the one provided (MFC.BSC is the browser database for NAFXCWD.LIB).
  157. The following instructions describe how to build the browse database using
  158. MFC's makefile and how to integrate the resulting .SBR files into your
  159. project.
  160.  
  161. By building the library with either the BROWSE=1 or BROWSEONLY=1
  162. options you can create the browse database files for the MFC source code.
  163. The output browse file (.BSC) will be placed in the source directory
  164. (this allows the browser to find the source files). The browse
  165. database files share a common naming convention with the libraries.
  166.  
  167. Usually, it is sufficient to build only one browse database, although
  168. you can build a browse variant for each library variant that MFC
  169. supports.  In addition, it is possible to build only the browse database,
  170. instead of building all the object files and library file.  To build
  171. the NAFXCWD.BSC file, for example:
  172.  
  173.     NMAKE DEBUG=1 BROWSEONLY=1
  174.  
  175. The output will be placed in NAFXCWD.BSC (in the MFC source directory).
  176. In addition, all of the SBR files (the individual files, which when combined,
  177. form the .BSC) will be preserved in the OBJ directory (in this case $NWD).
  178. You can add these SBR files to your project's browse database, enabling you to
  179. browse the MFC source as well as your application source code at the same time.
  180.  
  181. If you are using an external makefile, simply include the MFC SBRs in your
  182. BSCMAKE command.  For example:
  183.  
  184.     BSCMAKE /o myproj.sbr myfile1.sbr myfile2.sbr \msdev\mfc\src\$nwd\*.sbr
  185.  
  186. If you are using a Visual C++ project file, you can add it to your project
  187. settings.  To do so, load your project (.MDP or .MAK) file:
  188.  
  189.     - From the Build menu, choose Settings to edit your project settings
  190.     - Select the "Browse Info" tab in the settings dialog
  191.     - Choose the target you wish to add the MFC browse information
  192.         (ie. Win32 Debug or Win32 Retail)
  193.     - Add the browse files (.SBR files) to "Project Options" edit box:
  194.         \msdev\mfc\src\$nwd\*.sbr
  195.  
  196.       Note: Substitute the appropriate path if you built a different variant
  197.         of the library or installed VC++ in a different directory than the
  198.         default.
  199.  
  200. Even if you are using the incremental build option of BSCMAKE (the default),
  201. these files will not be truncated to zero length (the files are marked in a
  202. special way to prevent the normal truncation that occurs when doing incremental
  203. builds).
  204.  
  205. Note: The SBR files are protected from truncation by adding a special record
  206. (PCHMARK) that bscmake uses to protect SBR files that are refered to from
  207. pre-compiled header files (PCH).  This record consists of a single byte with
  208. the value 0x10.  The PCHMARK.BIN file contains this single byte -- it is
  209. appended to the SBR files during the build process.
  210.  
  211. You can also open the resulting browse database file directly and use it
  212. to browse MFC source code.
  213.  
  214.  
  215. ======================================
  216.  5. SOURCE CODE FORMATTING CONVENTION
  217. ======================================
  218.  
  219. All MFC source code has been formatted such that leading whitespace
  220. on a line is made up of physical tabs, while embedded whitespace is
  221. physical spaces.  MFC source code assumes that your editor is set to
  222. display a physical tab as four blanks.
  223.  
  224. For example:
  225.  
  226. int FormatExample()
  227. {
  228. // Statements below should start in column 5 if tabs are set correctly
  229. // Comment should start in column 20
  230. /*
  231. 0        1         2
  232. 12345678901234567890
  233. */
  234.     int i;
  235.     i = 5;         // whitespace between statement and comment is spaces
  236.  
  237.     return i;
  238.  
  239. }
  240.  
  241. More information on MFC coding and commenting conventions can be found
  242. in Technical Note #46.
  243.