documentation/clam_manual/clam_docs.html

   1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3   <head>
   4     <meta content="text/html; charset=iso-8859-1" http-equiv="content-type">
   5     <meta content="Fred T. Hamster" name="Author">
   6     <meta name="generator" content="Mozilla/5.0 (X11; U; Linux i686; en-US) [Mozilla]">
   7     <title>CLAM Reference Manual</title>
   8   </head>
   9   <body link="#33ff33" text="#ffff99" vlink="#009900" bgcolor="#400080" alink="#ff9900">
  10     <center><big>
  11       </big><small></small>
  12       <h1><big>CLAM: Coordinated Librarian &amp;</big></h1>
  13       <h1><big>Automatic Maker</big></h1>
  14       <small></small></center>
  15     <center><big><img src="../../infobase/pictures/clams_tran.gif" height="347" width="392"></big></center>
  16     <center><big>
  17       </big><small></small>
  18       <h2><big>Tutorial and Reference Manual</big></h2>
  19       <small></small></center>
  20     <center><big>
  21       </big><small></small>
  22       <address><big><a name="lib_manager"></a>By Chris Koeritz (<a href="mailto:koeritz@gruntose.com">koeritz@gruntose.com</a>)</big></address>
  23       <small></small></center>
  24     <center><big>
  25       </big><small></small>
  26       <h2><small></small>
  27         <hr noshade="noshade" size="8" width="100%"></h2>
  28       <small></small></center>
  29     <center><big>
  30       </big><small></small>
  31       <h2><big>Table of Contents</big></h2>
  32       <small></small></center>
  33     <ol>
  34       <small> </small><big> </big><small> </small>
  35       <li><big> <a href="#EXECUTIVE_SUMMARY">Executive Summary</a></big></li>
  36       <small> </small><big> </big><small> </small>
  37       <li><big> <a href="#PREPARATION">Preparing Your Computer to Use
  38             CLAM</a></big></li>
  39       <small> </small><big> </big><small> </small>
  40       <ol>
  41         <small> </small><big> </big><small> </small>
  42         <li><big> <a href="#STEPS_NEEDED">Necessary Steps</a></big></li>
  43         <small> </small><big> </big><small> </small>
  44       </ol>
  45       <small> </small><big> </big><small> </small>
  46       <li><big> <a href="#TUTORIAL">CLAM Tutorial</a></big></li>
  47       <small> </small><big> </big><small> </small>
  48       <ol>
  49         <small> </small><big> </big><small> </small>
  50         <li><big> <a href="#CAVEATS">Caveats</a></big></li>
  51         <small> </small><big> </big><small> </small>
  52         <li><big> <a href="#TUT_BASICS">Basics</a></big></li>
  53         <small> </small><big> </big><small> </small>
  54         <li><big> <a href="#TUT_COMMON">Common Files</a></big></li>
  55         <small> </small><big> </big><small> </small>
  56         <li><big> <a href="#TUT_IMPORTANT_VARS">Important Variables</a></big></li>
  57         <small> </small><big> </big><small> </small>
  58         <li><big> <a href="#TUT_VAR_ASSIGN">Variable Assignment</a></big></li>
  59         <small> </small><big> </big><small> </small>
  60         <li><big> <a href="#TUT_OPTIONAL_VARS">Optional Variables</a></big></li>
  61         <small> </small><big> </big><small> </small>
  62         <li><big> <a href="#WRITING_RULES">Writing Your Own Rules</a></big></li>
  63         <small> </small><big> </big><small> </small>
  64         <li><big> <a href="#TUT_CONCLUSION">Conclusion</a></big></li>
  65         <small> </small><big> </big><small> </small>
  66       </ol>
  67       <small> </small><big> </big><small> </small>
  68       <li><big> <a href="#REFERENCE">CLAM Reference</a></big></li>
  69       <small> </small><big> </big><small> </small>
  70       <ol>
  71         <small> </small><big> </big><small> </small>
  72         <li><big> <a href="#LANG_INDEP_VARS">Language Independent
  73               Variables</a></big></li>
  74         <small> </small><big> </big><small> </small>
  75         <li><big> <a href="#LANG_INDEP_RULES">Language Independent
  76               Rules</a></big></li>
  77         <small> </small><big> </big><small> </small>
  78         <li><big> <a href="#LANG_INDEP_TARGETS">Language Independent
  79               Targets</a></big></li>
  80         <small> </small><big> </big><small> </small>
  81         <li><big> <a href="#LANG_INDEP_SCRIPTS">Language Independent
  82               Files</a></big></li>
  83         <small> </small><big> </big><small> </small>
  84         <li><big> <a href="#CPP_VARS">C++ Specific Variables</a></big></li>
  85         <small> </small><big> </big><small> </small>
  86         <ol>
  87           <small> </small><big> </big><small> </small>
  88           <li><big> <a href="#DIRECTORY_VARS">Directory Structure
  89                 Variables</a></big></li>
  90           <small> </small><big> </big><small> </small>
  91           <li><big> <a href="#CPP_FLAGS">Compiler Dependent Flags</a></big></li>
  92           <small> </small><big> </big><small> </small>
  93           <li><big><a href="#vcpp_only">Microsoft Visual C++ Only</a><br>
  94             </big></li>
  95           <small> </small><big> </big><small> </small>
  96           <li><big> <a href="#SUPPORT_EXTENSIONS">Support for
  97                 Compilation
  98                 Extensions</a></big></li>
  99           <small> </small><big> </big><small> </small>
 100         </ol>
 101         <small> </small><big> </big><small> </small>
 102         <li><big> <a href="#CPP_RULES">C++ Specific Rules</a></big></li>
 103         <small> </small><big> </big><small> </small>
 104         <li><big> <a href="#CPP_TARGETS">C++ Specific Targets</a></big></li>
 105         <small> </small><big> </big><small> </small>
 106         <li><big> <a href="#CPP_SCRIPTS">C++ Specific Files</a></big></li>
 107         <small> </small><big> </big><small> </small>
 108       </ol>
 109       <small> </small><big> </big><small> </small>
 110       <li><big> <a href="#EXAMPLES">Example CLAM Makefiles</a></big></li>
 111       <small> </small><big> </big><small> </small>
 112       <li><big> <a href="#CLAM_HINTS">CLAM Hints and Troubleshooting</a></big></li>
 113       <small> </small><big> </big><small> </small>
 114       <li><big> <a href="#ACKS">Acknowledgements</a></big></li>
 115       <small> </small><small></small>
 116     </ol>
 117     <center><big>
 118       </big><small></small>
 119       <h2><small></small>
 120         <hr noshade="noshade" size="8" width="100%"></h2>
 121       <small></small></center>
 122     <center><big>
 123       </big><small></small>
 124       <h2><big><a name="EXECUTIVE_SUMMARY"></a>Executive Summary</big></h2>
 125       <small></small></center>
 126     <big>&nbsp;&nbsp;&nbsp; The CLAM system is a set of macros and rules
 127       for the GNU make program
 128       that
 129       simplifies the creation of executable programs and code
 130       libraries.&nbsp;
 131       Most makefiles that use the CLAM system are ten lines long or
 132       less.&nbsp;
 133       Makefiles are stated in terms of a set of special variable names that
 134       CLAM
 135       interprets in order to issue the correct sequence of compilation
 136       directives.&nbsp;
 137       This document presents a tutorial on the variable names and simple
 138       rules
 139       that need to be used with CLAM. &nbsp;Several example makefiles and the
 140       full
 141       reference manual for CLAM are also included.<br>
 142       &nbsp;&nbsp;&nbsp; CLAM is part of the Feisty Meow® codebase (<a href="http://feistymeow.org/">http://feistymeow.org/</a>)
 143       and can be
 144       downloaded from there or through a sourceforge mirror site.<br>
 145       &nbsp;&nbsp;&nbsp; In the remainder of the document, we will often
 146       refer to CLAM as just "clam".<br>
 147       &nbsp;
 148     </big>
 149     <center><small></small>
 150       <h2><small></small>
 151         <hr noshade="noshade" size="8" width="100%"></h2>
 152       <small></small></center>
 153     <center><big>
 154       </big><small></small>
 155       <h2><big><a name="PREPARATION"></a>Preparing Your Computer to Use
 156           CLAM</big></h2>
 157       <small></small></center>
 158     <h3><big><a name="STEPS_NEEDED"></a>Necessary Steps:</big></h3>
 159     <ol>
 160       <small> </small><big> </big><small> </small>
 161       <li><big>Setting environment variables for clam:</big></li>
 162       <small> </small><big> </big><small> </small>
 163       <ol>
 164         <li><big>FEISTY_MEOW_APEX:</big></li>
 165         <small> </small><big> </big><small> </small>
 166         <ol>
 167           <small> </small><big> </big><small> </small>
 168
 169 <big>DEPRECATED</big>
 170           <li><big> **REVISE** out of date... This variable has been needed
 171               since clam became
 172               part of the YETIcode project (at <a href="http://feistymeow.org/">http://feistymeow.org</a>).</big></li>
 173           <small> </small>
 174           <li><big>The default location for clam is under the FEISTY_MEOW_SCRIPTS directory in a
 175               folder named clam.<br>
 176             </big></li>
 177           <small> </small><big> </big><small> </small>
 178           <li><big>If the yeti root directory is in $HOME/yeti
 179               already, then the
 180               default for FEISTY_MEOW_APEX will work and it doesn't need to be
 181               declared.</big></li>
 182           <li><big>Setting the variable:<br>
 183             </big></li>
 184           <small> </small><big> </big><small> </small>
 185           <ol>
 186             <small> </small><big> </big><small> </small>
 187             <li><big>On Unix (with the bash shell): <span style="font-weight: bold;">export
 188                   MAKEFLAGS="-I $HOME/yeti/clam"</span></big></li>
 189             <small> </small><big> </big><small> </small>
 190             <li><big>On win32: <span style="font-weight: bold;">set
 191                   MAKEFLAGS="-I c:/yeti/clam"</span>&nbsp; (or set this in the
 192                 System
 193                 control panel, under the advanced tab, in environment variables)<span
 194                   style="font-weight: bold;"><br>
 195                 </span></big></li>
 196             <small> </small><big> </big><small> </small>
 197             <li><big>Note that the use of
 198                 forward slashes is mandatory in the clam directory in MAKEFLAGS.<br>
 199               </big></li>
 200             <small> </small><big> </big><small> </small>
 201           </ol>
 202           <small> </small><big> </big><small> </small>
 203         </ol>
 204         <small> </small><big> </big><small> </small>
 205         <li><big>MAKEFLAGS:</big></li>
 206         <small> </small><big> </big><small> </small>
 207         <ol>
 208           <small> </small><big> </big><small> </small>
 209           <li><big> This variable is required to be set in the
 210               environment before using clam with gnu-make.&nbsp; It tells make
 211               where
 212               to find the clam definitions and scripts.</big></li>
 213           <small> </small>
 214           <li><big>Setting the variable:<br>
 215             </big></li>
 216           <small> </small><big> </big><small> </small>
 217           <ol>
 218             <small> </small><big> </big><small> </small>
 219             <li><big>On Unix (assuming bash as shell): <span style="font-weight: bold;">export
 220                   MAKEFLAGS="-I $FEISTY_MEOW_APEX/clam"</span></big></li>
 221             <small> </small><big> </big><small> </small>
 222             <li><big>On win32: <span style="font-weight: bold;">set
 223                   MAKEFLAGS="-I %FEISTY_MEOW_APEX%/clam"</span></big></li>
 224             <small> </small><big> </big><small> </small>
 225             <li><big>This variable also requires forward slashes
 226                 instead of
 227                 backslashes.</big></li>
 228             <small> </small><big> </big><small> </small>
 229           </ol>
 230           <small> </small><big> </big><small> </small>
 231         </ol>
 232         <small> </small>
 233       </ol>
 234       <small> </small>
 235       <li><big>Required Tools:</big></li>
 236       <small> </small><big> </big><small> </small>
 237       <ol>
 238         <small> </small><big> </big><small> </small>
 239         <li><big>The compiler itself:<br>
 240           </big></li>
 241         <small> </small><big> </big><small> </small>
 242         <ol>
 243           <small> </small><big> </big><small> </small>
 244           <li><big>If you are running GNU/Linux (or almost any other
 245               Posix-compliant operating system), then the GNU C/C++ compiler
 246               suite is pretty much all that's needed.</big></li>
 247           <small> </small><big> </big><small> </small>
 248           <li><big>The
 249               GNU C/C++ compiler (included in the <a href="http://www.mingw.org/">MinGW</a>
 250               toolkit) should be all that's needed for
 251               compilation,
 252               but the Microsoft Visual Studio 6.0-8.0 compilers can be used if
 253               available.&nbsp; Compatibility is only guaranteed for vc8
 254               however.<br>
 255             </big></li>
 256           <small> </small><big> </big><small> </small>
 257         </ol>
 258         <small> </small><big> </big><small> </small>
 259         <li><big>Win32 Unix Tools:</big></li>
 260         <small> </small><big> </big><small> </small>
 261         <ol>
 262           <small> </small><big> </big><small> </small>
 263           <li><big>&nbsp;If you are running a win32-based product
 264               (windows NT,
 265               windows
 266               2000,
 267               windows xp, etc) then a few additional tools are required...<br>
 268             </big></li>
 269           <small> </small><big> </big><small> </small><small></small>
 270           <li><big>The recommended GNU utilities are available for
 271               win32 in the
 272               MingW MSYS
 273               package (http://www.mingw.org/).</big></li>
 274           <li><big>Note that you will need to add the binaries directory from
 275               MSYS to
 276               your path.&nbsp; The PATH variable can be accessed under MS-NT
 277               type OSes through the
 278               "control panel | system | advanced | environment variables" menu
 279               trail.&nbsp; If you
 280               plan to use msys outside of clam, then ensure that
 281               the MSYS bin directory is prior to the
 282               windows system directory in your path; this causes the Unix "find"
 283               command to be used instead of the Windows version.</big></li>
 284           <li><big>Alternatively, a similar set of GNU utilities is
 285               available
 286               in the <a href="http://cygwin.com/">Cygwin package</a>, although
 287               these tools are no longer recommended and are, in
 288               fact, actively deprecated.</big></li>
 289           <small> </small><big> </big><small> </small>
 290           <ol>
 291             <small> </small><big> </big><small> </small>
 292           </ol>
 293           <small> </small><big> </big><small> </small>
 294         </ol>
 295         <small> </small><big> </big><small> </small>
 296         <li><big>makedep and version_stamper tools:</big></li>
 297         <small> </small><big> </big><small> </small>
 298         <ol>
 299           <small> </small><big> </big><small> </small>
 300           <li><big>The CLAM_BINARIES directory in the archive has
 301               pre-built
 302               versions of tools used by clam during a build.<br>
 303             </big></li>
 304           <small> </small><big> </big><small> </small>
 305           <li><big>If you would rather rebuild them from source, then
 306               running
 307               the script "scripts/generator/produce_feisty_meow.sh" will
 308               recreate all of these internal tools.<br>
 309             </big></li>
 310           <small> </small><big> </big><small> </small>
 311         </ol>
 312         <small> </small><big> </big><small> </small>
 313       </ol>
 314       <small> </small><big> </big><small> </small>
 315       <li><big>Third Party Tools Used By or Supported Within clam:</big></li>
 316       <small> </small><big> </big><small> </small>
 317       <ol>
 318         <small> </small><big> </big><small> </small>
 319         <li><big>wx widgets:</big></li>
 320         <small> </small><big> </big><small> </small>
 321         <ol>
 322           <small> </small><big> </big><small> </small>
 323           <li><big>home page: http://www.wxwidgets.org/</big></li>
 324           <small> </small><big> </big><small> </small>
 325           <li><big>As far as the clam team is concerned, this is the
 326               premier
 327               portable (and open source) library for graphical user interfaces.<br>
 328             </big></li>
 329           <small> </small><big> </big><small> </small>
 330         </ol>
 331         <small> </small><big> </big><small> </small>
 332         <li><big>OpenSSL:</big></li>
 333         <small> </small><big> </big><small> </small>
 334         <ol>
 335           <small> </small><big> </big><small> </small>
 336           <li><big>home page: http://www.openssl.org/</big></li>
 337           <small> </small><big> </big><small> </small>
 338           <li><big>This is the team's most favorite library for SSL
 339               (Secure
 340               Sockets Layer) and general encryption needs.<br>
 341             </big></li>
 342           <small> </small><big> </big><small> </small>
 343         </ol>
 344         <small> </small><big> </big><small> </small>
 345         <li><big>cURL:</big></li>
 346         <small> </small><big> </big><small> </small>
 347         <ol>
 348           <small> </small><big> </big><small> </small>
 349           <li><big>home page: http://curl.haxx.se/</big></li>
 350           <small> </small><big> </big><small> </small>
 351           <li><big>The curl library rocks(!) and provides a very
 352               powerful set of
 353               tools for programmatically interacting with live web pages.<br>
 354             </big></li>
 355           <small> </small><big> </big><small> </small>
 356         </ol>
 357         <small> </small><big> </big><small> </small>
 358       </ol>
 359       <small> </small><big> </big><small> </small>
 360       <li><big>Other clam Preconditions:</big></li>
 361       <small> </small><big> </big><small> </small>
 362       <ol>
 363         <small> </small><big> </big><small> </small>
 364         <li><big>Linux platforms:</big></li>
 365         <small> </small><big> </big><small> </small>
 366         <ol>
 367           <small> </small><big> </big><small> </small>
 368           <li><big>The standard source code repository is a directory
 369               called
 370               "feisty_meow"
 371               in the user's home directory. &nbsp;If you decompress the feisty_meow
 372               library archive in your home directory, you should be all set to
 373               perform a build.</big></li>
 374           <small> </small><big> </big><small> </small>
 375           <li><big>See the Feisty Meow Concerns Ltdwebsite for more details about
 376               downloading that codebase (<a href="http://feistymeow.org">http://feistymeow.org</a>).<br>
 377             </big></li>
 378           <small> </small><big> </big><small> </small>
 379           <ol>
 380             <small></small><small></small>
 381           </ol>
 382           <small> </small><big> </big><small> </small>
 383         </ol>
 384         <small> </small><big> </big><small> </small>
 385         <li><big>Win32 platforms:</big></li>
 386         <small> </small><big> </big><small> </small>
 387         <ol>
 388           <small> </small><big> </big><small> </small>
 389           <li><big>The standard repository for source code is a substituted
 390               drive l:, which is where all the other hierarchies start.
 391               &nbsp;This
 392               drive can be mapped to any folder desired using the "subst"
 393               command
 394               (for example, "subst l: c:\build_dir").
 395               &nbsp;All
 396               objects and final products will be generated to the l: drive.</big></li>
 397           <small> </small><big> </big><small> </small>
 398           <li value="2"><big>Using MS Visual Studio as the Compiler:</big></li>
 399           <small> </small><big> </big><small> </small>
 400           <ol>
 401             <small> </small><big> </big><small> </small>
 402             <li><big>VS80COMNTOOLS/VS90COMNTOOLS/VS100COMNTOOLS variable:</big></li>
 403             <small> </small><big> </big><small> </small>
 404             <ol>
 405               <small> </small><big> </big><small> </small>
 406               <li><big>This variable should be automatically created by
 407                   Visual Studio upon installation.&nbsp; If it isn't, then
 408                   Microsoft has
 409                   a bug or you need to restart your current prompt or your
 410                   computer.<br>
 411                 </big></li>
 412               <li><big>The paths that clam uses to find compiler binaries
 413                   is calculated based on this variable.</big></li>
 414               <li><big>Older versions of visual studio are currently
 415                   unsupported because Microsoft constantly rearranges their
 416                   folders and
 417                   tools in a non-maintainable way.<br>
 418                 </big></li>
 419             </ol>
 420             <li><big>Several other environment variables are required
 421                 by Visual
 422                 Studio.&nbsp; They can be set up for your current command prompt
 423                 by
 424                 running "vcvars32.bat" or "vsvars32.bat" (found under
 425                 the
 426                 compiler's common directory, which varies depending on the
 427                 version of
 428                 visual studio).<br>
 429               </big></li>
 430             <small> </small><big> </big><small> </small>
 431           </ol>
 432           <small> </small><big> </big><small> </small>
 433         </ol>
 434         <small> </small><big> </big><small> </small>
 435       </ol>
 436       <small> </small><small></small>
 437     </ol>
 438     <center><big>
 439       </big><small></small>
 440       <h2><small></small>
 441         <hr noshade="noshade" size="8" width="100%"></h2>
 442       <small></small></center>
 443     <center><big>
 444       </big><small></small>
 445       <h2><big><a name="TUTORIAL"></a>CLAM Tutorial</big></h2>
 446       <small></small></center>
 447     <big>&nbsp;&nbsp;&nbsp;&nbsp; This section provides an overview of
 448       how clam
 449       works and how you can make it work for you.&nbsp; It is quite brief,
 450       but
 451       should suffice for most common cases of makefiles.&nbsp; For more
 452       detailed
 453       usage, consult the CLAM Reference section of this document.
 454     </big>
 455     <h3><big><a name="CAVEATS"></a>Caveats</big></h3>
 456     <ul>
 457       <small> </small><big> </big><small> </small>
 458       <li><big>Most of the Unix tools employed in the make process are
 459           case-sensitive.&nbsp;
 460           This means that they will probably not find any of the clam support if
 461           the files have been changed to upper-case names.&nbsp; It also means
 462           that
 463           all code files must match their descriptions in makefiles, letter for
 464           letter.&nbsp;
 465           And any batch files or executables invoked also need to be in
 466           lower-case
 467           as clam expects them to be.</big></li>
 468       <small> </small><big> </big><small> </small>
 469       <li><big>A corollary case requirement is that the makefile must
 470           be named
 471           either
 472           "makefile" or "Makefile".&nbsp; These are the Unix standard names and
 473           GNU make
 474           looks for these by default.&nbsp; If you are willing to type "make -f
 475           <i>makefile_name</i>",
 476           then you can run any makefile.&nbsp; However, the build-ready
 477           makefiles
 478           should be named according to the standard, since the build process
 479           will
 480           look for these automatically.</big></li>
 481       <small> </small><small></small>
 482     </ul>
 483     <h3><big>
 484         <a name="TUT_BASICS"></a>Basics</big></h3>
 485     <big>&nbsp;&nbsp;&nbsp;&nbsp; The C++ Library
 486       Automatic Maker system (or CLAM) is defined as a set of
 487       variable
 488       (or macro) definitions. &nbsp;These variable definitions are
 489       manipulated in
 490       order to compile and link programs.&nbsp; By setting the variables'
 491       values
 492       appropriately, specific products can be generated from the target rules
 493       defined
 494       in clam.&nbsp; Both variables and rules are extensible.&nbsp; The
 495       general
 496       procedure for building a clam-based Makefile has four user-defined
 497       steps:
 498     </big>
 499     <ol>
 500       <small> </small><big> </big><small> </small>
 501       <li><big>loading the default variables for clam,</big></li>
 502       <small> </small><big> </big><small> </small>
 503       <li><big>redefining the default variables where necessary,</big></li>
 504       <small> </small><big> </big><small> </small>
 505       <li><big>loading the default rule set for clam,</big></li>
 506       <small> </small><big> </big><small> </small>
 507       <li><big>defining rules that are local to the user's Makefile.</big></li>
 508       <small> </small><small></small>
 509     </ol>
 510     <big>Step 4 can usually be omitted unless the project creates
 511       components
 512       whose types are not supported by clam.<br>
 513       &nbsp;&nbsp;&nbsp;&nbsp; clam is structured as a directory hierarchy
 514       where the root of clam
 515       supports
 516       the most general makefile activities. &nbsp;Activities such as
 517       recursing
 518       into subdirectories and providing support for cleaning up after a make
 519       are
 520       provided at this level. &nbsp; In the remainder of the document, we
 521       will
 522       designate this location with a "$" character to clarify what part of
 523       the clam hierarchy we are describing.<br>
 524       &nbsp; &nbsp;&nbsp; The root clam
 525       support files are mostly language independent, since they are used by
 526       all
 527       varieties of language dependent derived versions of clam.&nbsp; These
 528       files
 529       are generally not of concern unless one is designing a new derived
 530       version
 531       of clam for a language not yet supported.<br>
 532       &nbsp;&nbsp;&nbsp;&nbsp; The subdirectories off of the clam root
 533       provide
 534       "derived" makefile services, such as C++ or Ada compilation.&nbsp; Each
 535       derived clam service implements at least two files to link into the
 536       rest of the
 537       clam system: a variables file and a rules file. &nbsp;The variables
 538       file defines
 539       the options for the derived make process; by changing the values of
 540       these,
 541       different types of targets can be created. &nbsp;The rules file
 542       implements
 543       creation of the targets relevant to the programming language being
 544       supported.<br>
 545       &nbsp;&nbsp; &nbsp; It may be worth noting that clam can be used to
 546       drive
 547       any kind of programmatic process--not just compilation. &nbsp;Currently
 548       though,
 549       program compilation is the primary goal.
 550     </big>
 551     <h3><big><a name="TUT_COMMON"></a>Common Files</big></h3>
 552     <big>&nbsp;&nbsp;&nbsp;&nbsp; The top-level file called
 553       "$/variables.def"
 554       contains
 555       definitions and descriptions of the variables used throughout the clam
 556       system.&nbsp; For a non-derived type of make (using only base clam
 557       support),
 558       this file should be included near the start of the user's
 559       Makefile.&nbsp;
 560       The rules file (stored in "$/rules.def") should be included after the
 561       user
 562       has modified the appropriate variables that will dictate how the make
 563       is
 564       performed.
 565       <br>
 566       &nbsp;&nbsp;&nbsp;&nbsp; This scheme of including variables at the
 567       top and then rules at the bottom of the user's makefile is employed in
 568       all clam makefiles.&nbsp; For example, makefiles for C++ compilation
 569       are structured the
 570       same way.&nbsp; The user's C++ makefile includes the C++ variables
 571       (stored
 572       in a subdirectory called "$/cpp" under the clam root) at the top of the
 573       makefile and then includes the C++ rules at the bottom.<br>
 574       &nbsp;&nbsp;&nbsp;&nbsp; An example
 575       of a C++ makefile is shown below:
 576     </big>
 577     <ul>
 578       <small> </small><big> <tt>include cpp/variables.def <br>
 579           <br>
 580           PROJECT = basis<br>
 581           TYPE = library<br>
 582           SOURCE = chaos.cpp checkup.cpp earth_time.cpp guards.cpp istring.cpp \<br>
 583           &nbsp; log_base.cpp mutex.cpp occurrence.cpp outcome.cpp
 584           outcome_table.cpp \<br>
 585           &nbsp; packable.cpp portable.cpp runtime_history.cpp
 586           system_outcomes.cpp \<br>
 587           &nbsp; utility.cpp version_checker.cpp version_record.cpp<br>
 588           TARGETS = basis.lib<br>
 589           <br>
 590           include cpp/rules.def</tt><br>
 591       </big><small></small>
 592     </ul>
 593     <big>The interior of the makefile overrides the TYPE, SOURCE
 594       and TARGETS variables for C++ compilation to specify what is to be
 595       built
 596       (basis.lib) and what it consists of (the CPP files mentioned in
 597       SOURCE).&nbsp;
 598       &nbsp;The PROJECT variable being overridden is actually defined in the
 599       $/variables.def;
 600       a project name is a required feature of all clam makefiles.
 601     </big>
 602     <h3><big><a name="TUT_IMPORTANT_VARS"></a>Important Variables</big></h3>
 603     <big>&nbsp;&nbsp;&nbsp;&nbsp;
 604       The clam root directory is pointed to by an internal variable called
 605       "CLAM_SCRIPTS",
 606       defined in $/variables.def.&nbsp; This variable is used by the clam
 607       system
 608       to find extra files that might be needed by derived makefile
 609       support.&nbsp;
 610       It is important to change this to the appropriate value when you are
 611       using the system in a different location. &nbsp;The CLAM_SCRIPTS variable
 612       can either
 613       be directly edited in $/variables.def, or it can be overridden in the
 614       environment
 615       of the shell running the make, or it can be passed on the command line
 616       to
 617       make.<br>
 618       &nbsp;&nbsp;&nbsp;&nbsp; For C++ compilation, the above example
 619       makefile
 620       (for basis.lib) contains examples for most of the required
 621       elements.&nbsp; Additional elements
 622       will be discussed in the examples section or can be found in the
 623       reference.&nbsp;
 624       The absolutely required variables for C++ are PROJECT, TYPE, SOURCE and
 625       TARGETS.
 626     </big>
 627     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; PROJECT is a variable that
 628         provides the
 629         name
 630         of the project being compiled.&nbsp; This should be a word that can
 631         also
 632         be used as a directory name and partial component of filenames.&nbsp;
 633         Thus,
 634         spaces and other unusual punctuation characters are discouraged.&nbsp;
 635         All of the project's temporary directories will be created based on
 636         this
 637         variable.&nbsp; This project name should be unique across a full build;
 638         otherwise files generated by compiling identical project names will be
 639         jumbled together.
 640       </big></p>
 641     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; TYPE is a variable that describes
 642         the kind
 643         of project that is being compiled.&nbsp; This is necessary because it
 644         controls
 645         some aspects of the compilation, such as where the compilation products
 646         are
 647         generated.&nbsp; All files generated by compilation are stored in the
 648         repository
 649         directory (by default, either "/opt/feistymeow.org/feisty_meow" in Linux or "l:\" in
 650         win32).&nbsp; There are three TYPEs supported so far: </big></p>
 651     <ul>
 652       <small> </small><big> </big><small> </small>
 653       <li><big>library: indicates that the project will primarily be
 654           creating
 655           static
 656           or
 657           dynamic libraries.</big></li>
 658       <small> </small><big> </big><small> </small>
 659       <li><big>application: indicates that the project will create
 660           executables.</big></li>
 661       <small> </small><big> </big><small> </small>
 662       <li><big>test: indicates that the project constructs test
 663           programs.</big></li>
 664       <small> </small><small></small>
 665     </ul>
 666
 667 <big>DEPRECATED</big>
 668     <big>
 669
 670 &nbsp;&nbsp;&nbsp; &nbsp;Projects of the "library" type will
 671       be given
 672       an include directory named after the project, such as
 673
 674       "/opt/feistymeow.org/feisty_meow/include/basis".
 675       &nbsp;The include directory is created as a copy of the headers in the
 676       project's
 677       directory .&nbsp; Library projects will also have their final products
 678       copied
 679       to the lib or dll subdirectories of the build directory being created.<br>
 680       &nbsp;&nbsp;&nbsp; &nbsp;Projects that are of type "application" will
 681       have their executables
 682       copied to the executable directory in the repository (such as
 683       "~/hoople/exe").
 684
 685 <br>
 686       &nbsp; &nbsp; &nbsp;The "test" type of project
 687       will be promoted to a subdirectory named after the PROJECT that resides
 688       under the test hierarchy in the repository (such as
 689       "~/hoople/tests/turbodog").
 690     </big>
 691
 692 <big>DEPRECATED</big>
 693     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; SOURCE is a list of files that
 694         are to be
 695         compiled
 696         in order to create the final products of the project.&nbsp; These can
 697         be
 698         C++ source files (*.cpp), MS-Win32 resource files (*.rc) and other
 699         types
 700         of source files.&nbsp; The list of objects to create will be determined
 701         by transforming the list of SOURCE files (such as by turning a file
 702         called
 703         "fud.cpp" into an object called "fud.obj").
 704       </big></p>
 705     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; TARGETS is a list of the products
 706         that are
 707         to be created by compilation and linking.&nbsp; The suffix of a target
 708         is a well established extension, such as ".lib", ".exe"
 709         or ".dll" for MS-Win32 compilation products.
 710       </big></p>
 711     <h3><big><a name="TUT_VAR_ASSIGN"></a>Variable Assignment Policies</big></h3>
 712     <big>&nbsp;&nbsp;&nbsp;&nbsp;
 713       The assignment of variable values is mostly straightforward, but it
 714       might
 715       be valuable to provide a refresher.&nbsp; In GNU make, a variable
 716       (a.k.a.
 717       macro) can be assigned using the following syntax:
 718     </big>
 719     <ul>
 720       <small> </small><big>FRED = a b c </big><small> </small>
 721     </ul>
 722     <big>This sets the variable named FRED to the value of "a
 723       b c". &nbsp;The variable is referred to as $(FRED) when it is being
 724       used,
 725       although its name is just FRED.<br>
 726       &nbsp;&nbsp;&nbsp; &nbsp;This syntax is fine when the variable is to be
 727       defined only once.&nbsp;
 728       In many cases though, a variable is already defined and needs to be
 729       added
 730       to instead of redefined.&nbsp; Using the standard equals (=) operator
 731       would
 732       wipe out the previous definition, so a special assignment
 733       is provided:
 734     </big>
 735     <ul>
 736       <small> </small><big>FRED += d e f </big><small> </small>
 737     </ul>
 738     <big>This is quite similar to the C syntax on integers.&nbsp; It
 739       means that
 740       FRED will be given a value equal to its old value plus the new
 741       contents.&nbsp;
 742       In our example, FRED would be equal to "a b c d e f". &nbsp;Note that
 743       one cannot say:<br>
 744       <br>
 745       &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; FRED = $(FRED) d e f
 746       &nbsp; &nbsp; &nbsp; (BAD!)<br>
 747       <br>
 748       This is not allowed in GNU make because it includes a macro's own value
 749       in its definition. &nbsp;This causes a badly formed recursive
 750       definition
 751       of the variable; a variable dereferencing operation (such
 752       as $(FRED)) causes the variable's current value to
 753       be resolved, which in turn dereferences any other variables in the
 754       definition.
 755       &nbsp;Thus, the reference to $(FRED) causes infinite recursion when
 756       included
 757       in the definition of FRED.<br>
 758       <br>
 759       &nbsp;&nbsp;&nbsp;&nbsp; In the case of variables that <u>must</u>
 760       be defined by the user's makefile, the standard assignment operator
 761       (via the = character) can
 762       be used.&nbsp; This includes the PROJECT, TYPE, SOURCE, and TARGETS
 763       variables.&nbsp;
 764       Also, any other variables that are set only by the user's makefile can
 765       use simple assignment.&nbsp; This category includes LOCAL_LIBS_USED,
 766       LIBS_USED and others of similar nature.<br>
 767       &nbsp;&nbsp;&nbsp;&nbsp; But several variables are defined partially
 768       by clam, then added to within the user's makefile, and then possibly
 769       extended
 770       after the user's makefile is processed (by the clam rules file).&nbsp;
 771       These variables cannot use
 772       standard assignment and must instead use the incremental assignment
 773       (+=)
 774       operator.&nbsp; Variables included in this category are DEFINITIONS,
 775       LOAD_FLAG_PREFIX,
 776       CLEANUPS, and many others.
 777       <br>
 778       &nbsp;&nbsp;&nbsp;&nbsp; If you are unsure about the type of variable
 779       you are defining, then the incremental assignment (+=) operator is
 780       preferred
 781       to avoid trashing the variable's previous values.<br>
 782       &nbsp;&nbsp;&nbsp;&nbsp;
 783       Note that when variables are "exported", then any make in a subshell
 784       will
 785       inherit the parent shell's value.&nbsp; This can induce some weird
 786       behavior
 787       for variables that are incrementally constructed with the +=
 788       operator.&nbsp;
 789       If this seems to be happening, try using the simple assignment operator
 790       for
 791       that variable in the sub-makefile, if this is allowed. &nbsp;In general
 792       though,
 793       variables are not exported unless they MUST be seen by shell scripts
 794       and
 795       this does not occur overly frequently.
 796     </big>
 797     <h3><big><a name="TUT_OPTIONAL_VARS"></a>Optional Variables</big></h3>
 798     <big>&nbsp;&nbsp;&nbsp;&nbsp; There are several miscellaneous
 799       variables that
 800       are useful, either within one's makefiles or when passed to GNU make on
 801       the command
 802       line.&nbsp; These are described below.
 803     </big>
 804     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; LOCAL_LIBS_USED is a list of
 805         library names
 806         that are to be linked in with the library or executable being
 807         created.&nbsp;
 808         These are specially formatted names; they are just the prefix part of
 809         the
 810         full library name.&nbsp; For example, if you're building a release
 811         executable
 812         and want to link in a data structures library "i_adt.lib" (win32) or
 813         "libi_adt.a" (Linux), you can specify:
 814         <br>
 815         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; LOCAL_LIBS_USED = i_adt
 816         <br>
 817         The appropriate prefix and suffix will be attached.
 818       </big></p>
 819     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; EXTRA_COPIES is a list of files
 820         that should be copied to a project's output folder when it is done
 821         being compiled.&nbsp; These should be files that are not already
 822         copied as the main products, such as extra data or configuration files
 823         that belong with an application.
 824       </big></p>
 825     <p><big>&nbsp;&nbsp;&nbsp;&nbsp; EXTRA_VERSIONS is a list of
 826         version files
 827         that
 828         also need to be updated to the main build version during a
 829         compilation.&nbsp;
 830         These are usually needed if a project compiles several executable
 831         files,
 832         and each one performs version checking.&nbsp; (By default, any project
 833         containing a file called "version.ini" will get a version stamp from
 834         the
 835         main build version.)
 836       </big></p>
 837     <h3><big><a name="WRITING_RULES"></a>Writing Your Own Rules</big></h3>
 838     <big>&nbsp;&nbsp;&nbsp;&nbsp; One might need to write new rules
 839       for
 840       processing
 841       file types that are not directly supported by clam.&nbsp; There are a
 842       number
 843       of features provided for writing rules, but there are also some
 844       requirements
 845       placed on the rules.
 846       <br>
 847       &nbsp;&nbsp;&nbsp;&nbsp; All rules in makefiles need to be prefaced
 848       with one of the provided "launcher" macros.&nbsp; These are used to
 849       ensure
 850       that the rules can be properly executed on different platforms;
 851       Windoze95
 852       was especially hard to implement for until these macros were developed
 853       (due to what appear to be basic defects in the command line
 854       support).&nbsp;
 855       All preaching aside, here are the macros:
 856     </big>
 857     <ul>
 858       <small> </small><big> </big><small> </small>
 859       <li><big>HIDER: Executes a command but hides the
 860           invocation.&nbsp; Any
 861           output is
 862           still sent to standard out.&nbsp; If a verbose
 863           build is being done, then all of the invocations become visible again.</big></li>
 864       <small> </small><big> </big><small> </small>
 865       <li><big>HIDESH: Executes a shell script but hides the
 866           invocation.
 867           &nbsp;Similar to HIDER but supports scripts specifically.<br>
 868         </big></li>
 869       <small> </small><small></small>
 870     </ul>
 871     <big>Here are some examples of using the macros properly.&nbsp;
 872       Note that
 873       the
 874       command itself must be contained in single quotes:<br>
 875       <br>
 876       $(HIDER) $(MIDL) crumpet_server.idl<br>
 877     </big>
 878     <blockquote><big>MIDL is also a provided macro; it executes the
 879         Microsoft
 880         IDL compiler. </big></blockquote>
 881     <big>$(HIDESH) $(CLAM_SCRIPTS)/postconditions.sh<br>
 882     </big>
 883     <blockquote><big>This runs a shell script that handles the end
 884         portion of a
 885         make.</big></blockquote>
 886     <h3><big>
 887         <a name="TUT_CONCLUSION"></a>Conclusion</big></h3>
 888     <big>&nbsp;&nbsp;&nbsp;&nbsp; This tutorial is intended to raise
 889       awareness
 890       of
 891       basic&nbsp; usage.&nbsp; Hopefully the reader will now be able to
 892       create
 893       simple makefiles that use .&nbsp; For more aggressive compilation
 894       requirements,
 895       the reference section may be needed; it describes every variable and
 896       rule
 897       used in the&nbsp; system.&nbsp; However, it is most likely the case
 898       that
 899       your unsupported compilation needs will also be required by others in
 900       the
 901       future, and it is hoped that you will contribute them to the
 902       main-line&nbsp; support.&nbsp; Currently, the appropriate way to do
 903       this is just
 904       to
 905       send the makefile code to the <a href="#lib_manager">library
 906         administrator</a>, who will include them
 907       in the next version of .
 908     </big>
 909     <center><small></small>
 910       <h2><small></small>
 911         <hr noshade="noshade" size="8" width="100%"></h2>
 912       <small></small></center>
 913     <center><big>
 914       </big><small></small>
 915       <h2><big><a name="REFERENCE"></a>CLAM Reference</big></h2>
 916       <small></small></center>
 917     <h2><big>
 918         <a name="LANG_INDEP_VARS"></a><u>Language Independent Variables</u></big></h2>
 919     <big>&nbsp;&nbsp;&nbsp;&nbsp; The language independent variables
 920       are stored
 921       in the file "$/variables.def".&nbsp; They define the overall structure
 922       of a make and can usually be overridden to customize how the make is
 923       performed.
 924     </big>
 925     <h4><big>BUILD_BEFORE</big></h4>
 926     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of projects that need
 927       to be
 928       created
 929       before this project can be created.&nbsp; The items in the list are
 930       interpreted
 931       as directories that contain a makefile to be run.&nbsp; For example, if
 932       an item in BUILD_BEFORE is listed as ?fred?, then the target
 933       "fred.make"
 934       will be executed.&nbsp; That target changes to the directory 'fred'
 935       before
 936       running the makefile there.&nbsp; The project in the specified
 937       directory
 938       is created using make if needed (as determined by that directory's
 939       Makefile).&nbsp;
 940       The projects in BUILD_BEFORE are made immediately after the
 941       FIRST_TARGETS
 942       are made.
 943     </big>
 944     <h4><big>ACTUAL_TARGETS, ACTUAL_FIRST_TARGETS, ACTUAL_LAST_TARGETS</big></h4>
 945     <big>&nbsp;&nbsp; &nbsp; See below for TARGETS, FIRST_TARGETS and
 946       LAST_TARGETS.<br>
 947     </big>
 948     <h4><big>BUILD_AFTER</big></h4>
 949     <big>&nbsp;&nbsp;&nbsp;&nbsp; A list of directory names that
 950       should be
 951       recursed
 952       into after this project finishes. &nbsp;Each listed directory will have
 953       make
 954       started on any makefile found.<br>
 955     </big>
 956     <h4><big>BUILD_BEFORE<br>
 957       </big></h4>
 958     <big>&nbsp;&nbsp;&nbsp;&nbsp; A list of directory names that
 959       should be
 960       recursed into before this project
 961       starts. &nbsp;Each directory listed will have make started on any
 962       makefile found.<br>
 963     </big>
 964     <h4><big>MAKEFILE_NAME</big></h4>
 965     <big>&nbsp;&nbsp;&nbsp;&nbsp; A variable that specifies the name
 966       of the
 967       makefile
 968       for all sub-makes.&nbsp; It works with BUILD_BEFORE and
 969       BUILD_AFTER and allows the name of the makefile in a
 970       subdirectory to be changed to something other than 'makefile'.&nbsp;
 971       This
 972       supports different types of builds which are controlled by different
 973       makefile
 974       names.
 975     </big>
 976     <h4><big>PARAMETER_FILE</big></h4>
 977     <big>&nbsp;&nbsp;&nbsp; &nbsp;A file name that is
 978       usually found at the root of the repository. &nbsp;The name is
 979       often "build.ini", but any name can be used as the parameter file.
 980       &nbsp;This file is an extension of the variable set included in
 981       $/variables.def
 982       and can be used to provide compilation paramters without resorting to
 983       the
 984       command line. &nbsp;This file is associated with a particular build
 985       rather
 986       than the&nbsp; support, so different releases will have different build
 987       parameter
 988       files. &nbsp;On systems supporting version information, the build's
 989       version
 990       number is stored here also.<br>
 991     </big>
 992     <h4><big>CATCHER</big></h4>
 993     <big>&nbsp;&nbsp;&nbsp; &nbsp;A sub-program launcher like HIDESH
 994       but this will trap errors it sees and play the build error
 995       CLAM_ERROR_SOUND.<br>
 996     </big>
 997     <h4><big>CLAM_BINARIES</big></h4>
 998     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a folder where the helper
 999       binaries for the CLAM makefile system are located.  <br>
1000     </big>
1001     <h4><big>CLAM_SCRIPTS</big></h4>
1002     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable points at the location
1003       where the&nbsp; definitions and helper scripts are located.&nbsp; The
1004       default is
1005       "~/yeti/clam",
1006       but this can be overridden for local installations of .<br>
1007     </big>
1008     <h4><big>CLAM_ERROR_SOUND</big></h4>
1009     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of sound files
1010       that should be played when a make stops with an error. &nbsp;It serves
1011       as
1012       an audible warning that something bad happened.<br>
1013     </big>
1014     <h4><big>CLAM_FINISH_SOUND</big></h4>
1015     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of sound files
1016       that should be played when the make has concluded
1017       successfully. &nbsp;It should play when the outer-most make
1018       has seen all targets created as intended.<br>
1019     </big>
1020     <h4><big>CLAM_TMP</big></h4>
1021     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies the location for temporary
1022       files generated during a make. &nbsp;The default value usually works
1023       fine.
1024       &nbsp;This directory will be created if it does not already exist.<br>
1025     </big>
1026     <h4><big>CLEANUPS</big></h4>
1027     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of files to be
1028       removed by the
1029       make
1030       clean command.&nbsp; They are possibly acquired from the TARGETS
1031       defined
1032       in the user's Makefile, or by language dependent rules for
1033       cleaning.&nbsp;
1034       Additional files can be added to this list by the user's makefile also.
1035     </big>
1036     <h4><big>DIRTY_FILE</big></h4>
1037     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable points at a file that
1038       signifies
1039       that some targets have been remade.&nbsp; It is not used at the base
1040       level
1041       of clam, but language-specific versions might do something special if
1042       targets
1043       were remade (such as put them in a build repository).
1044     </big>
1045     <h4><big>FAILURE_FILE</big></h4>
1046     <big>&nbsp;&nbsp;&nbsp;&nbsp; This file is used as a flag that
1047       indicates
1048       when
1049       a make has failed.&nbsp; The particular file used depends on the
1050       project
1051       name for this makefile.&nbsp; It is cleared at both the beginning and
1052       end
1053       of a make.
1054     </big>
1055     <h4><big>FIRST_TARGETS</big></h4>
1056     <big>&nbsp;&nbsp;&nbsp;&nbsp; The FIRST_TARGETS are made before
1057       any
1058       libraries
1059       are created and before any executables are compiled.&nbsp; There must
1060       be
1061       a rule for making every entry in this list, either through implicit
1062       rules
1063       or explicit ones provided by the user's makefile.
1064     </big>
1065     <h4><big>FLAG_FILES</big></h4>
1066     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of all the files
1067       that are used for compilation flags. &nbsp;They are whacked at the
1068       beginning
1069       and end of a make.<br>
1070     </big>
1071     <h4><big>HIDER</big></h4>
1072     <big>&nbsp;&nbsp;&nbsp;&nbsp; This macro is used throughout&nbsp;
1073       to hide the
1074       commands that are being sent to the operating system.&nbsp; It can be
1075       disabled to allow a verbose make (see the NOISY macro).
1076     </big>
1077     <h4><big>HIDESH</big></h4>
1078     <big>&nbsp;&nbsp;&nbsp;&nbsp; Just like HIDER, but this macro is
1079       specifically
1080       for launching shell scripts. &nbsp;Some versions of GNU make (like
1081       Cygwin's)
1082       have problems running scripts which don't arise when running executable
1083       files.
1084       &nbsp;Those problems led to the creation of the HIDESH macro for those
1085       specific
1086       cases. &nbsp;This is not an issue for Unix systems.
1087     </big>
1088     <h4><big>&nbsp;LAST_TARGETS</big></h4>
1089     <big>&nbsp;&nbsp;&nbsp;&nbsp; The LAST_TARGETS are made after all
1090       of the
1091       other
1092       standard targets are made.&nbsp; Their must be a rule for making every
1093       entry in this list, either through implicit rules or explicit ones
1094       provided
1095       by the user's makefile.
1096     </big>
1097     <h4><big>NOISY</big></h4>
1098     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable can be used to cause a
1099       verbose
1100       make.&nbsp;
1101       If the variable is non-empty, then all commands will be echoed to
1102       standard
1103       output.&nbsp; Otherwise, the default is to hide the commands that are
1104       issued
1105       and just show the output of running those commands.
1106     </big>
1107     <h4><big>OP_SYSTEM</big></h4>
1108     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a flag that defines the
1109       operating
1110       system
1111       name.&nbsp; This flag is sometimes used to choose the appropriate tools
1112       per platform or to conditionally compile code for system
1113       dependent interfaces.&nbsp; The available possibilities so far are
1114       UNIX,
1115       OS2, SYSV (System V Unix), DOS, and WIN32.&nbsp; Only UNIX and WIN32
1116       are
1117       currently very functional.
1118     </big>
1119     <h4><big>&nbsp;OTHER_CLEANS</big></h4>
1120     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are targets to execute before
1121       performing
1122       the main clean up during "make clean".&nbsp; These might be targets
1123       that
1124       contain shell commands to execute as part of clean up or they could
1125       contain
1126       the "clean_subdirs" command (defined below).
1127     </big>
1128     <h4><big>PROJECT</big></h4>
1129     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a variable that provides the
1130       name of
1131       the
1132       project being compiled.&nbsp; This should be a word that can also be
1133       used
1134       as a directory name and as a partial component of filenames.&nbsp;
1135       Thus, spaces
1136       and other unusual punctuation characters are discouraged.&nbsp; All of
1137       the project's temporary directories will be created based on this
1138       variable.
1139     </big>
1140     <h4><big>FEISTY_MEOW_APEX</big></h4>
1141     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies the root directory
1142       for compilation or other&nbsp; building activities. &nbsp; The
1143       repository
1144       is also where source code and final products of compilation reside,
1145       unless
1146       the default is over-ridden (see TARGETS_STORE).<br>
1147     </big>
1148     <h4><big>SH &amp; SHELL</big></h4>
1149     <big>&nbsp;&nbsp;&nbsp;&nbsp; These variables both point at a
1150       shell program
1151       that is
1152       used for starting commands. &nbsp;SHELL is defined by GNU make, whereas
1153       SH is defined by .
1154     </big>
1155     <h4><big>SUB_FLAG_FILES</big></h4>
1156     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of the compilation
1157       flag files
1158       which
1159       should be destroyed only at the end of a make.&nbsp; They are used for
1160       communication
1161       with submakefiles--makefiles that were invoked by "this" makefile.<br>
1162     </big>
1163     <h4><big>SUBMAKE_FLAG</big></h4>
1164     <big>&nbsp;&nbsp;&nbsp; &nbsp;This points to a file whose presence
1165       indicates
1166       that
1167       a "submake" performed some actions. &nbsp;The flag can be interpreted
1168       by
1169       some language-specific versions of&nbsp; as a reason to set a flag
1170       using
1171       the
1172       DIRTY_FILE.<br>
1173     </big>
1174     <h4><big>TARGETS</big></h4>
1175     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are the products to be created
1176       by .&nbsp;
1177       Each item listed in TARGETS should have a rule that knows how to create
1178       that type of file.&nbsp; The language independent system provides very
1179       few suffix based rules.&nbsp; TARGETS is filled in by the user in
1180       their&nbsp; file, but it is not used directly by the&nbsp;
1181       system.&nbsp;
1182       Instead,
1183       a generated variable called ACTUAL_TARGETS is used.<br>
1184     </big>
1185     <h4><big>TARGETS_STORE</big></h4>
1186     <big>&nbsp;&nbsp;&nbsp;&nbsp; This folder is where all generated
1187       files are
1188       to
1189       be stored. &nbsp;It is usually identical to FEISTY_MEOW_APEX but can be
1190       overridden
1191       when the targets should be stored elsewhere.<br>
1192     </big>
1193     <h4><big>Version components: major, minor, revision, build<br>
1194       </big></h4>
1195     <big>&nbsp;&nbsp;&nbsp; &nbsp;These four variables specify the
1196       version of
1197       this
1198       particular build. &nbsp;They are usually stored in the
1199       PARAMETER_FILE.
1200       &nbsp;The major and minor versions are the traditional 2.3, 4.0, etc
1201       style
1202       of release numbers. &nbsp;The revision number is often used to sequence
1203       the
1204       builds of that particular release, such that build 3.5.127 is the 127th
1205       build
1206       of the 3.5 release.<br>
1207       &nbsp; &nbsp; &nbsp;A version-tagged file (such as an executable or
1208       dynamic
1209       library) with any one of the major, minor or revision numbers differing
1210       from
1211       an installed build is incompatible with the installed build. &nbsp;An
1212       executable
1213       file or dynamic library will not be allowed to load other dynamic
1214       libraries
1215       where these numbers differ.<br>
1216       &nbsp; &nbsp; &nbsp;The last version component is misleadingly called
1217       "build";
1218       this number specifies the service pack level for a file. &nbsp;Files
1219       whose
1220       versions only differ in the last "build" component are intended to be
1221       compatible
1222       with each other. &nbsp;The understanding is that if only that number
1223       differs,
1224       then the external interface to the file has not changed, although the
1225       interior
1226       implementation may have.<br>
1227     </big>
1228     <h2><big><a name="LANG_INDEP_RULES"></a><u>Language Independent
1229           Rules</u></big></h2>
1230     <big>&nbsp;&nbsp;&nbsp;&nbsp; The file "$/rules.def" uses the
1231       composite
1232       macros
1233       defined in "$/variables.def" together with a set of make rules to
1234       perform
1235       actions during compilation.&nbsp; The rules file should be included in
1236       the user's Makefile after the compilation variables have been
1237       initialized
1238       for the project being compiled.&nbsp; The user's own targets should be
1239       placed after the directive that includes "$/rules.def".
1240     </big>
1241     <h4><big>%.halt</big></h4>
1242     <big>&nbsp;&nbsp;&nbsp;&nbsp; These targets cause&nbsp; to exit,
1243       usually to
1244       avoid
1245       something that it considers catastrophic.&nbsp; An example of this
1246       would
1247       be when&nbsp; finds an inappropriate entry in the list of objects to
1248       create;
1249       allowing a "make clean" on this makefile will delete files that are
1250       probably
1251       not intended.&nbsp; Hence, when&nbsp; finds this kind of usage, it will
1252       stop the make and issue a complaint.
1253     </big>
1254     <h4><big>%.make</big></h4>
1255     <big>&nbsp;&nbsp;&nbsp;&nbsp; Used to compile a makefile in a
1256       subdirectory
1257       named
1258       "%".&nbsp; This rule is employed by the BUILD_BEFORE macro, but can be
1259       used in the user's makefile targets also.
1260     </big>
1261     <h2><big><a name="LANG_INDEP_TARGETS"></a><u>Language Independent
1262           Targets</u></big></h2>
1263     <big>&nbsp;&nbsp;&nbsp; The following targets are defined by
1264       "$/rules.def".
1265     </big>
1266     <h4><big>all</big></h4>
1267     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a standard target that is
1268       executed
1269       when
1270       no particular target is specified at the make command line.&nbsp; It is
1271       an umbrella target that invokes all of the other targets required to
1272       perform
1273       a make.&nbsp; The order in which the major targets are created is:
1274     </big>
1275     <ol>
1276       <small> </small><big> </big><small> </small>
1277       <li><big>FIRST_TARGETS</big></li>
1278       <small> </small><big> </big><small> </small>
1279       <li><big>TARGETS</big></li>
1280       <small> </small><big> </big><small> </small>
1281       <li><big>LAST_TARGETS</big></li>
1282       <small> </small><small></small>
1283     </ol>
1284     <h4><big>
1285         clean</big></h4>
1286     <big>&nbsp;&nbsp;&nbsp;&nbsp; This causes all of the files in
1287       CLEANUPS to be
1288       removed and also executes all of the targets in OTHER_CLEANS.&nbsp; The
1289       language dependent system can override some of this behavior or it can
1290       just add more files to the list of CLEANUPS.
1291     </big>
1292     <h4><big>clean_subdirs</big></h4>
1293     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is similar to "make_subdirs" in
1294       that it
1295       descends
1296       into the subdirectories in no particular order, but it runs "make
1297       clean"
1298       in each of them.&nbsp; This allows a directory hierarchy of projects to
1299       be cleaned with one command.
1300     </big>
1301     <h4><big>finish</big></h4>
1302     <big>&nbsp;&nbsp;&nbsp;&nbsp; The "finish" target represents the
1303       completion
1304       of a make, whether successful or not.&nbsp; It reports the time and
1305       date
1306       (and logs them).
1307     </big>
1308     <h4><big>rm_links</big></h4>
1309     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target causes all link files in
1310       the
1311       current
1312       directory to be deleted.&nbsp; This is only applicable on a Unix
1313       operating
1314       system.
1315     </big>
1316     <h4><big>make_subdirs</big></h4>
1317     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target allows a makefile to
1318       specify that
1319       all of the subdirectories under the current directory should be scanned
1320       for makefiles and that those makefiles should be executed.&nbsp; If a
1321       makefile
1322       does not exist, it is skipped.&nbsp; Note that the subdirectories are
1323       descended
1324       into in no particular order; the order depends on how the operating
1325       system
1326       decides to list the directories.&nbsp; If the order of make is
1327       important,
1328       use BUILD_BEFORE instead.
1329     </big>
1330     <h4><big>start</big></h4>
1331     <big>&nbsp;&nbsp;&nbsp;&nbsp; The "start" target represents the
1332       beginning of
1333       the make.&nbsp; It reports the time and date (and logs them).
1334     </big>
1335     <h2><big><a name="LANG_INDEP_SCRIPTS"></a><u>Language Independent
1336           Files</u></big></h2>
1337     <h4><big>$(PARAMETER_FILE)</big></h4>
1338     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a special
1339       file that has at least two purposes in .&nbsp; It is the source of
1340       the
1341       version number that will be stamped on all the appropriate DLLs and
1342       EXEs
1343       created during a build.&nbsp; It is also a place where build-wide
1344       compilation
1345       directives can be included so that they do not have to be passed on the
1346       command
1347       line.&nbsp; For C++ compilation, this is usually an INI file
1348       stored in the
1349       FEISTY_MEOW_APEX under the build folder.&nbsp;
1350       Here is a sample parameter file:
1351     </big>
1352     <blockquote><big><tt><font size="-1"><big>#\</big></font></tt> <br>
1353         <tt><font size="-1"><big>[version]</big></font></tt> <br>
1354         <tt><font size="-1"><big>major=14</big></font></tt> <br>
1355         <tt><font size="-1"><big>minor=3</big></font></tt> <br>
1356         <tt><font size="-1"><big>revision=140</big></font></tt> <br>
1357         <tt><font size="-1"><big>build=0</big></font></tt> </big><small> </small>
1358       <p><big><tt><font size="-1"><big>DEBUG=t</big></font></tt> <br>
1359           <tt><font size="-1"><big>OPTIMIZE=t</big></font></tt> <br>
1360         </big></p>
1361       <small> </small></blockquote>
1362     <big>Note the bizarre comment at the top of the makefile; this is
1363       used to
1364       hide
1365       the "[version]" section marker.&nbsp; The comment is required because
1366       the
1367       build parameter file is pulled directly into the makefile code to set
1368       the
1369       variables after the version stamp.&nbsp; Without a comment in front of
1370       the section, a syntax error would result.&nbsp; The "[version]" section
1371       marker is required because this file is also sometimes treated as a
1372       win32 INI file
1373       in order to read the version stamp.<br>
1374       &nbsp;&nbsp;&nbsp;&nbsp; The build version is stored in the first four
1375       entries.&nbsp; Our interpretation of the stamp is standard for "major"
1376       and "minor".&nbsp; We treat the "revision" as a build revision number;
1377       within a release, there will be numerous revisions--one for each new
1378       build
1379       that is performed.&nbsp; We then treat the "build" entry as a patch
1380       level
1381       within that particular build.&nbsp; When we perform our version
1382       checking,
1383       only the first three entries are compared; the patch level in "build"
1384       is
1385       considered irrelevant.
1386       <br>
1387       &nbsp;&nbsp;&nbsp;&nbsp; This example also specifies that the build
1388       should be a debug style (rather than release) build and that it should
1389       be optimizer.&nbsp; We can also see that
1390       the flags for bounds checker instrumentation and true time
1391       analysis support are commented out.<br>
1392     </big>
1393     <h4><big>badness_catcher.sh</big></h4>
1394     <big>&nbsp;&nbsp;&nbsp; &nbsp;Runs the command line passed
1395       in as a sub-shell and looks for error conditions. &nbsp;If an error
1396       occurred,
1397       the build is stopped and the CLAM_ERROR_SOUND is played.<br>
1398     </big>
1399     <h4><big>datestamp.sh</big></h4>
1400     <big>&nbsp;&nbsp;&nbsp; &nbsp;Echoes the time and date. &nbsp;This
1401       is a
1402       separate
1403       file to make the cross-platform difference less annoying.<br>
1404     </big>
1405     <h4><big>exit_make.sh</big></h4>
1406     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to stop dead in its
1407       tracks.
1408     </big>
1409     <h4><big>postconditions.sh</big></h4>
1410     <big>&nbsp;&nbsp;&nbsp; &nbsp;Invoked at the end of the
1411       language-invariant
1412       portion of a make.<br>
1413     </big>
1414     <h4><big>preconditions.sh</big></h4>
1415     <big>&nbsp;&nbsp;&nbsp; &nbsp;Invoked at the beginning of the
1416       language-invariant portion of a make.<br>
1417     </big>
1418     <h4><big>starter.sh</big></h4>
1419     <big>&nbsp;&nbsp;&nbsp;&nbsp; This shell script executes a command
1420       that is
1421       passed
1422       to it as its parameters and logs error conditions to standard
1423       output.&nbsp;
1424       It's used by the CATCHER macro.
1425     </big>
1426     <h2><small></small>
1427       <hr noshade="noshade" size="8" width="100%"></h2>
1428     <h2><big>
1429         <a name="CPP_VARS"></a><u>C++ Specific Variables</u></big></h2>
1430     <big>&nbsp;&nbsp;&nbsp;&nbsp; These variables are used throughout
1431       the C++
1432       compilation
1433       support.&nbsp; They are defined in "$/cpp/variables.def".
1434     </big>
1435     <h4><big>BASE_CPU</big></h4>
1436     <big>&nbsp;&nbsp;&nbsp;&nbsp; Allows specification of the
1437       processor that the
1438       build is targeted for.&nbsp; This is needed when special actions must
1439       be
1440       taken for different processor types.&nbsp; Valid values currently
1441       include
1442       m68k (for Motorola 68000 series), m68340 (specifically the 68340),
1443       x86 (intel 386 and upwards), and ppc860 (the PowerPC 860).
1444     </big>
1445     <h4><big>BUILD_LIST_FILE</big></h4>
1446     <big>&nbsp;&nbsp;&nbsp; &nbsp;The list of files that must
1447       be rebuilt. &nbsp;This is only used with compilers that support
1448       compilation
1449       of multiple source files with one invocation of the compiler (currently
1450       only
1451       MS-Visual C++).<br>
1452     </big>
1453     <h4><big>BUILD_WHACK_FILE</big></h4>
1454     <big>&nbsp;&nbsp;&nbsp; &nbsp;A list of object files that must be
1455       destroyed
1456       if
1457       the make fails. &nbsp;This is only relevant in the same situations as
1458       BUILD_LIST_FILE.<br>
1459     </big>
1460     <h4><big>COMPILER</big></h4>
1461     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable chooses the specific
1462       flags
1463       needed
1464       for the compiler.&nbsp; Not all operating system choices above are
1465       suitable
1466       with the COMPILER choices, but generally it is fairly obvious which are
1467       supported.&nbsp; The current possibilities include BORLAND_DOS,
1468       BORLAND_OS2,
1469       UNIX (default cc), GNU_OS2, GNU_LINUX, OBJECT_CENTER (Saber compiler),
1470       SUN_UNIX,
1471       VISUAL_CPP, and DIAB3.
1472     </big>
1473     <h4><big>COMPILER_FLAGS</big></h4>
1474     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the list of flags passed to
1475       the
1476       preprocessor
1477       and compiler. It is composed of the SYSTEM, the DEFINITIONS, the
1478       SEARCH_DIRS,
1479       and any user-included options. If flags that don't fit one of the
1480       categories
1481       are needed, they can be added here.
1482     </big>
1483     <h4><big>CONSOLE_MODE</big></h4>
1484     <big>&nbsp;&nbsp;&nbsp;&nbsp; This causes the program
1485       to be generated as a console application.&nbsp; This is relevant in
1486       systems
1487       (such as win32) where programs have a split personality depending on
1488       whether
1489       they are to have graphical user interfaces or just console interfaces.
1490     </big>
1491     <h4><big>DEBUG_FLAGS</big></h4>
1492     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are flags used for generating
1493       specialized
1494       versions of object files, such as ones that include debugging code
1495       (e.g.,
1496       for gdb) or ones that add code for profiling (e.g., gprof). Possible
1497       values
1498       in the Sun CenterLine Compiler environment are -g for debugging code
1499       and
1500       -pg for profiling.
1501     </big>
1502     <h4><big>DEFINITIONS</big></h4>
1503     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of compiler flags
1504       that define
1505       the
1506       value of C or C++ macros. These usually have the format of
1507       ?-D&lt;flag&gt;?,
1508       but in this particular variable only the &lt;flag&gt; itself should be
1509       listed
1510       (because the compiler option characters ?-D? are added automatically).
1511     </big>
1512     <h4><big>DEPENDENCY_ADDITIONS</big></h4>
1513     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of extra flags that
1514       gets passed
1515       to the auto-dependency tool.&nbsp; The list can vary for each compiler.
1516     </big>
1517     <h4><big>DEPS_FILE</big></h4>
1518     <big>&nbsp;&nbsp;&nbsp;&nbsp; This file is where the
1519       auto-dependency
1520       information
1521       is stored.&nbsp; The "makedep" program is used to generate
1522       auto-dependency
1523       information for the files listed in SOURCE.&nbsp; During a build, the
1524       DEPS_FILE
1525       is pulled into the actual code of the makefile; this causes the
1526       dependencies
1527       to be automatically included so that they can dictate the files that
1528       need
1529       to be rebuilt.
1530     </big>
1531     <h4><big>EXTRA_VERSIONS</big></h4>
1532     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of version files that
1533       also need
1534       to be updated to the main build version during a compilation.&nbsp;
1535       These
1536       are usually needed if a project compiles several executable files, and
1537       each one performs version checking.&nbsp; By default, any project
1538       containing
1539       a file called "version.ini" will get a version stamp from the main
1540       build
1541       version.
1542     </big>
1543     <h4><big>LIBRARIAN_FLAGS</big></h4>
1544     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of flags that are
1545       passed to the
1546       library creation tool.&nbsp; Sometimes this must be overridden for a
1547       particular
1548       compiler.
1549     </big>
1550     <h4><big>LIBS_USED</big></h4>
1551     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are code libraries that the
1552       executables
1553       depend upon.&nbsp; They are searched for in any of the directories
1554       listed
1555       in the LIBRARY_SEARCH_PATH.
1556     </big>
1557     <h4><big>LOAD_FLAG_PREFIX &amp; LOAD_FLAG_SUFFIX</big></h4>
1558     <big>&nbsp;&nbsp;&nbsp;&nbsp; These tell the linker and loader how
1559       to deal
1560       with
1561       the files and where to locate library components. The prefix is listed
1562       on the compilation command line before the object files are listed, and
1563       the suffix after. The prefix should contain information such as the
1564       directories
1565       to be searched for code libraries (although they should be added to
1566       LIBRARY_SEARCH_PATH).&nbsp;
1567       In the suffix definition, actual library loading statements (like
1568       -lmath)
1569       can be included (although they should be listed in a different form in
1570       LIBS_USED or LOCAL_LIBS_USED).
1571     </big>
1572     <h4><big>LOCAL_LIBS_USED</big></h4>
1573     <big>&nbsp;&nbsp;&nbsp;&nbsp; The names in this list actually
1574       cause the
1575       OBJECTS
1576       to be recompiled when the libraries listed have changed.&nbsp; To
1577       accomplish
1578       this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather
1579       than
1580       at some arbitrary place on the LIBRARY_SEARCH_PATH.&nbsp; These
1581       libraries
1582       also must follow the special naming convention followed by ; if
1583       "basis"
1584       is an entry in this list, then a library called "basis.lib" will be
1585       sought
1586       during the build.
1587     </big>
1588     <h4><big>NO_COMPILE</big></h4>
1589     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies that no compilation
1590       should be performed. &nbsp;Nothing in the SOURCE or TARGETS macros will
1591       be
1592       built.<br>
1593     </big>
1594     <h4><big>NO_DEPS</big></h4>
1595     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is an exclusion flag.&nbsp; If
1596       it is
1597       defined,
1598       then no auto-dependency files will be generated.&nbsp; This is useful
1599       if
1600       you're missing the makedep tool and trying to compile it.<br>
1601     </big>
1602     <h4><big>OBJECTS</big></h4>
1603     <big>&nbsp;&nbsp;&nbsp;&nbsp; The OBJECTS are all those files that
1604       need to
1605       be
1606       created during compilation.&nbsp; Usually this list is filled based on
1607       the files in SOURCE.
1608     </big>
1609     <h4><big>OPTIMIZE</big></h4>
1610     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create optimized
1611       code.&nbsp;
1612       The default optimization is for speed.
1613     </big>
1614     <h4><big>REBUILD</big></h4>
1615     <big>&nbsp;&nbsp;&nbsp;&nbsp; If the REBUILD variable is
1616       non-empty, then all
1617       files listed in the SOURCE variable are touched.&nbsp; This should
1618       cause
1619       all of those files to be rebuilt during the compilation.&nbsp;
1620       Occasionally
1621       GNU make will complain that a file is newer than the current time, but
1622       this does not usually cause any problems.
1623     </big>
1624     <h4><big>SOURCE</big></h4>
1625     <big>&nbsp;&nbsp;&nbsp;&nbsp; The SOURCE variable is a list of
1626       files that
1627       are
1628       to be compiled in order to create the final products of the
1629       project.&nbsp;
1630       These can be C++ source files (*.cpp), Win32 resource files (*.rc)
1631       and
1632       other types of source files.&nbsp; The list of objects to create will
1633       be
1634       determined by transforming the list of SOURCE files (such as by turning
1635       a file called "fud.cpp" into an object called "fud.obj").&nbsp; More
1636       file
1637       types will be added as they are needed.
1638     </big>
1639     <h4><big>STATIC</big></h4>
1640     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create statically
1641       linked
1642       targets.&nbsp;
1643       Executables or dynamic libraries will not link in any compiler supplied
1644       dynamic libraries, nor will they require them during run-time.
1645     </big>
1646     <h4><big>TYPE</big></h4>
1647     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a variable that describes
1648       the kind of
1649       project that is being compiled.&nbsp; Knowing the type of project is
1650       necessary
1651       because it controls some elements of the compilation and also of the
1652       final
1653       promotion of the compiled products.&nbsp; There are three TYPEs
1654       supported
1655       so far:
1656     </big>
1657     <ul>
1658       <small> </small><big> </big><small> </small>
1659       <li><big>library: indicates that the project will be primarily
1660           creating
1661           static
1662           or
1663           dynamic libraries.</big></li>
1664       <small> </small><big> </big><small> </small>
1665       <li><big>application: indicates that the project will create
1666           executables.</big></li>
1667       <small> </small><big> </big><small> </small>
1668       <li><big>test: indicates that the project constructs test
1669           programs.</big></li>
1670       <small> </small><small></small>
1671     </ul>
1672     <big>Projects of the "library" type will follow the special&nbsp;
1673       rules for
1674       their include directory (which is created as a copy of headers in the
1675       library
1676       directory).&nbsp; Library projects will also have their final products
1677       copied to the lib or dll subdirectories of the build directory being
1678       created.&nbsp;
1679       Projects that are "application"s will have their executables copied to
1680       the executable directory in the build.&nbsp; And "test" projects will
1681       be
1682       promoted to a subdirectory named after the PROJECT that resides under
1683       the
1684       test hierarchy in the build.
1685     </big>
1686     <h2><big><a name="DIRECTORY_VARS"></a><u>C++ Directory Structure
1687           Variables</u></big></h2>
1688     <h4><big>BASE_OUTPUT_PATH</big></h4>
1689     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is the parent directory
1690       for object files generated for the specified type of CPU and the style
1691       of
1692       build (e.g. debug or release builds).<br>
1693     </big>
1694     <h4><big>CPU_BUILD_DIR</big></h4>
1695     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable can be used to
1696       distinguish
1697       directory
1698       names used for output.&nbsp; It includes the cpu name and the type of
1699       build.
1700     </big>
1701     <h4><big>DYNAMIC_LIBRARY_DIR</big></h4>
1702     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where dynamic
1703       libraries will be
1704       stored after creation.<br>
1705     </big>
1706     <h4><big>EXECUTABLE_DIR</big></h4>
1707     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where executable files
1708       will be
1709       stored after creation.<br>
1710     </big>
1711     <h4><big>FINAL_DIR</big></h4>
1712     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the directory
1713       where the
1714       finished
1715       compilation products are stored, currently only import libraries for
1716       dynamic libraries.&nbsp;
1717       It is usually a directory under the OUTPUT_PATH named "final".
1718     </big>
1719     <h4><big>HEADER_SEARCH_PATH</big></h4>
1720     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1721       will be
1722       searched
1723       for C++ header files (files ending in ?.h?).
1724     </big>
1725     <h4><big>HOOPLE_HEADERS</big></h4>
1726 <big>DEPRECATED</big>
1727     <big>&nbsp;&nbsp;&nbsp;&nbsp; The two standard places to look for
1728       headers
1729       (the repository and the third party directory) are listed in this
1730       variable.
1731     </big>
1732     <h4><big>HOOPLE_LIBRARIES</big></h4>
1733 <big>DEPRECATED</big>
1734     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where our libraries are
1735       located.&nbsp; It is usually a subdirectory called "lib" under the
1736       repository
1737       directory.
1738     </big>
1739     <h4><big>LIBRARY_SEARCH_PATH</big></h4>
1740     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1741       will be
1742       searched
1743       for C++ library archives (files ending in ".a" or ".lib").
1744     </big>
1745     <h4><big>LOCAL_HEADERS</big></h4>
1746     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable provides a way to
1747       include
1748       headers
1749       prior to the default locations in the search path.&nbsp; For example,
1750       if
1751       you are compiling locally and have some headers that are not present in
1752       the build you are using, then you can specify where they are in this
1753       variable.
1754     </big>
1755     <h4><big>LOCAL_LIBRARIES</big></h4>
1756     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable allows other library
1757       directories
1758       to be added prior to the default search locations.&nbsp; This enables
1759       substitute
1760       static or import libraries to be used instead of the standard ones
1761       present
1762       in the build.
1763     </big>
1764     <h4><big>STATIC_LIBRARY_DIR</big></h4>
1765     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the location where code
1766       libraries are
1767       to be copied during promotion and where they are to be searched for
1768       when
1769       listed in LOCAL_LIBS_USED.&nbsp; Under Unix, these libraries have a
1770       ?.a?
1771       suffix and are created with the "ar" program.&nbsp; Under Win32,
1772       these
1773       libraries have a ?.lib? suffix and are created with "link".
1774     </big>
1775     <h4><big>OBJECT_DIR</big></h4>
1776     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where object files will be
1777       stored
1778       during
1779       compilation for the target type being produced.
1780     </big>
1781     <h4><big>OUTPUT_DIRECTORY_LIST</big></h4>
1782     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1783       need to be
1784       created under the OUTPUT_PATH.&nbsp; It contains the "final" directory
1785       where all finished products are stored, as well as all the intermediate
1786       directories for objects.
1787     </big>
1788     <h4><big>OUTPUT_PATH</big></h4>
1789     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the temporary file storage
1790       area.&nbsp;
1791       Any files that are created during the compilation process will be
1792       stored
1793       under here in a subdirectory named after the PROJECT.
1794     </big>
1795     <h4><big>OUTPUT_ROOT</big></h4>
1796     <big>&nbsp;&nbsp;&nbsp;&nbsp; This specifies the root portion of
1797       the
1798       OUTPUT_PATH.&nbsp;
1799       It lets a PC build use drive letters for the root, while a Unix build
1800       can
1801       specify a directory hierarchy.
1802     </big>
1803     <h4><big>SEARCH_DIRS</big></h4>
1804     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1805       will be
1806       searched
1807       for both C++ header files and for C++ code libraries.&nbsp; The items
1808       placed
1809       on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the
1810       HEADER_SEARCH_PATH.&nbsp;
1811       The reasoning behind this variable is lost in antiquity.
1812     </big>
1813     <h4><big>TESTS_DIR <br>
1814       </big></h4>
1815     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where test programs
1816       will be
1817       stored after creation.<br>
1818     </big>
1819     <h4><big>THIRD_PARTY_DIR</big></h4>
1820     <big>&nbsp;&nbsp;&nbsp;&nbsp; Third party components are sometimes
1821       used in
1822       the
1823       creation of products.&nbsp; The directory is expected to have a
1824       structure
1825       containing "include" and "lib" subdirectories where headers and
1826       libraries
1827       are stored.
1828     </big>
1829     <h2><big><a name="CPP_FLAGS"></a><u>Compiler Dependent Flags</u></big></h2>
1830     <h4><big>
1831         CC</big></h4>
1832     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the C++ compiler
1833       executable.
1834     </big>
1835     <h4><big>COMPILER_HEADER_DIR</big></h4>
1836     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the compiler's header
1837       (or
1838       include)
1839       root directory is located.&nbsp; It is usually based on the root
1840       directory.
1841     </big>
1842     <h4><big>COMPILER_LIBRARY_DIR</big></h4>
1843     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the code libraries for
1844       the
1845       compiler
1846       are located.&nbsp; It is usually based on the root directory.
1847     </big>
1848     <h4><big>COMPILER_ROOT_DIR</big></h4>
1849     <big>&nbsp;&nbsp;&nbsp;&nbsp; This should automatically be set to
1850       the
1851       appropriate
1852       local directory where the C++ compiler is located.
1853     </big>
1854     <h4><big>CREATE_LIBRARY_FLAG</big></h4>
1855     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag, if required, specifies
1856       the text
1857       that
1858       must precede the name of a library to create.&nbsp; It is passed to the
1859       library creation tool.
1860     </big>
1861     <h4><big>DEF_FILE</big></h4>
1862     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Win32
1863       programs.&nbsp;
1864       It specifies the name of a DEF file for all of the products created in
1865       the project.
1866     </big>
1867     <h4><big>LIB_PREFIX &amp; LIB_SUFFIX</big></h4>
1868     <big>&nbsp;&nbsp;&nbsp; &nbsp;The portions of a library's name
1869       dictated by the operating system. &nbsp;For example, on Unix the prefix
1870       is "lib"
1871       and the suffix is ".a", leading to library names like "libbasis.a" for
1872       the
1873       basis library. &nbsp;On win32, the prefix is "" and the suffix is
1874       ".lib", leading
1875       to library names like "basis.lib".<br>
1876     </big>
1877     <h4><big>LIBRARY_NAME_FLAG</big></h4>
1878     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag contains the text that
1879       specifies a
1880       library
1881       that will be included in a link.&nbsp; It is often "-l".
1882     </big>
1883     <h4><big>LIBRARY_PATH_FLAG</big></h4>
1884     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag provides the text needed
1885       to add
1886       another
1887       library search path.&nbsp; Multiple occurrences of this flag followed
1888       by
1889       a directory name are allowed by most compilers.
1890     </big>
1891     <h4><big>LIBRARY_TOOL</big></h4>
1892     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program
1893       responsible
1894       for
1895       creating libraries.
1896     </big>
1897     <h4><big>LINK_TOOL</big></h4>
1898     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program that
1899       links.&nbsp;
1900       This is sometimes the same as the compiler (CC) and sometimes the same
1901       as the librarian (LIBRARY_TOOL).
1902     </big>
1903     <h4><big>LINKER_OPTION_SEPARATOR</big></h4>
1904     <big>&nbsp;&nbsp;&nbsp;&nbsp; In some compilers, linker options
1905       need to be
1906       separated
1907       from compiler options that occur on the same command line.&nbsp; This
1908       flag
1909       serves that purpose.
1910     </big>
1911     <h4><big>LINKER_OUTPUT_FLAG</big></h4>
1912     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is sometimes required by a
1913       linker
1914       for
1915       specifying the name of the library or executable that it is creating.
1916     </big>
1917     <h4><big>OBJECT_NAME_FLAG</big></h4>
1918     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is used to specify the
1919       name of an
1920       object
1921       file being created.&nbsp; It is passed to the compiler to override
1922       whatever
1923       default name would be used.
1924     </big>
1925     <h2><big><u><a name="vcpp_only"></a>Microsoft-Visual C++ Only</u><br>
1926       </big></h2>
1927     <h4><big>USE_MFC</big></h4>
1928     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Visual C++
1929       and
1930       indicates
1931       that MFC is to be used in creating this project.&nbsp; This is usually
1932       the case for GUI applications.
1933     </big>
1934     <h4><big>VC_ROOT</big></h4>
1935     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is an override that allows the
1936       compiler
1937       root
1938       directory to be customized without changing the&nbsp; code.&nbsp; If
1939       VC_ROOT
1940       is set (either in a makefile or as an external variable), then it will
1941       be used in place of the COMPILER_ROOT_DIR.&nbsp; The best way to use
1942       this
1943       override is as an external environment variable; this allows makefiles
1944       to remain the same despite your local configuration of the compiler.
1945       <br>
1946       &nbsp;&nbsp;&nbsp;&nbsp; Note that this variable should use
1947       forward-slashes,
1948       where DOS/Win32 would use backslashes.&nbsp; Also, if you have
1949       installed
1950       Visual C++ in a directory path containing space characters, then please
1951       use the 8.3 notation for the directories containing the spaces; this
1952       allows
1953       the name to be passed around successfully.&nbsp; For example...
1954     </big>
1955     <center><small></small><big> </big><big> </big><big> </big><big> </big><big></big><big></big><big>
1956       </big><big> </big><big> </big><big> </big><big>
1957       </big><big> </big><big> </big><big> </big><small> </small><small></small><small>
1958       </small><small> </small><small> </small><small> </small><small>
1959       </small><small> </small><small> </small><small> </small><small> </small><small></small><small>
1960       </small><small> </small><small> </small><small> </small>
1961       <table cellpadding="8" cellspacing="4">
1962         <tbody>
1963           <tr>
1964             <td><big> </big><small> </small>
1965               <center><big><u>If Visual C++ Is Installed In</u></big></center>
1966               <small> </small><big> </big></td>
1967             <td><big> </big><small> </small>
1968               <center><big><u>Then VC_ROOT Should Be</u></big></center>
1969               <small> </small><big> </big></td>
1970           </tr>
1971           <tr>
1972             <td><big> </big><small> </small>
1973               <center><big>c:\devstudio\vc</big></center>
1974               <small> </small><big> </big></td>
1975             <td><big> </big><small> </small>
1976               <center><big>c:/devstudio/vc</big></center>
1977               <small> </small><big> </big></td>
1978           </tr>
1979           <tr>
1980             <td><big> </big><small> </small>
1981               <center><big>c:\program files\devstudio\vc</big></center>
1982               <small> </small><big> </big></td>
1983             <td><big> </big><small> </small>
1984               <center><big>c:/progra~1/devstudio/vc</big></center>
1985               <small> </small><big> </big></td>
1986           </tr>
1987         </tbody>
1988       </table>
1989       <small></small></center>
1990     <h4><big>VCS_ROOT</big></h4>
1991     <big>&nbsp;&nbsp;&nbsp;&nbsp; Similarly to the VC_ROOT, this
1992       variable points
1993       at the root of the C# support for Visual Studio.Net.<br>
1994     </big>
1995     <h4><big>FRAMEWORK_DIR</big></h4>
1996     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable specifies the location
1997       of the
1998       .Net framework directory.&nbsp; On MS-Windows XP, the default should be
1999       fine.&nbsp; For MS-Windows 2000 or other Win32 OSes, the windows
2000       directory
2001       should be "winnt" instead.&nbsp; If the operating system is configured
2002       in a non-default way, the framework directory can be specified in an
2003       environment variable.<br>
2004     </big>
2005     <h4><big>VCPP_USE_BASE</big></h4>
2006     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that standard Win32
2007       libraries should
2008       be linked in.<br>
2009     </big>
2010     <h4><big>VCPP_USE_GUI</big></h4>
2011     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MFC libraries
2012       should be
2013       linked in.
2014     </big>
2015     <h4><big>VCPP_USE_OLE</big></h4>
2016     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the COM / OLE
2017       libraries should
2018       be linked in.
2019     </big>
2020     <h4><big>VCPP_USE_RPC</big></h4>
2021     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-RPC libraries
2022       should be
2023       linked in.<br>
2024     </big>
2025     <h4><big>VCPP_USE_SOCK</big></h4>
2026     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-WinSock
2027       libraries should
2028       be linked in.<br>
2029     </big>
2030     <h2><big><a name="CPP_RULES"></a><u>C++ Specific Rules</u></big></h2>
2031     <big>&nbsp;&nbsp;&nbsp;&nbsp; These types of targets have one
2032       thing in
2033       common;
2034       if any of the items that a target depends on in SOURCE or
2035       LOCAL_LIBS_USED
2036       or included files or whatever have changed since the last time the
2037       target
2038       was created, then it is recompiled.
2039     </big>
2040     <h4><big>%.bad</big></h4>
2041     <big>&nbsp;&nbsp;&nbsp; &nbsp;Causes the make to die. &nbsp;This
2042       is added when an incorrect file type is spotted in a list of targets.<br>
2043     </big>
2044     <h4><big>%.dll</big></h4>
2045     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create dynamically linked
2046       libraries from
2047       the SOURCE.
2048     </big>
2049     <h4><big>%.elf</big></h4>
2050     <big>&nbsp;&nbsp;&nbsp; &nbsp;Creates elf-formatted binaries for
2051       use with a
2052       firmware build (a specialized RTOS is the only one currently supported).<br>
2053     </big>
2054     <h4><big>%.exe</big></h4>
2055     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates an executable program
2056       using all
2057       of
2058       the objects and libraries specified.&nbsp; It is therefore important in
2059       a&nbsp; makefile to only have executables that depend on the same group
2060       of object files.&nbsp; The hidden agenda in the "exe" type of target is
2061       that a file ending in ".cpp" must exist; this is taken as the root of
2062       the
2063       executable.&nbsp; It should usually contain the main() function (or its
2064       equivalent).
2065     </big>
2066     <h4><big>%.lib</big></h4>
2067     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates static libraries from
2068       the files
2069       listed
2070       in OBJECTS.
2071     </big>
2072     <h4><big>%.nil</big></h4>
2073     <big>&nbsp;&nbsp;&nbsp; &nbsp;A blank target for test compiles.<br>
2074     </big>
2075     <h4><big>%.obj</big></h4>
2076     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create object files from C++
2077       source
2078       files
2079       (files ending in .c or .cpp).
2080     </big>
2081     <h4><big>%.res</big></h4>
2082     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create compiled resource files
2083       from RC
2084       files
2085       in the SOURCE list.
2086     </big>
2087     <h2><big><a name="CPP_TARGETS"></a><u>C++ Specific Targets</u></big></h2>
2088     <h4><big>
2089         check_requirements</big></h4>
2090     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target ensures that certain
2091       characteristics
2092       of the makefile are present.&nbsp; It complains and aborts the make if
2093       they are missing.
2094     </big>
2095     <h4><big>post_compilation</big></h4>
2096     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target finalizes the
2097       compilation by
2098       running
2099       the postconditions script.&nbsp; If PROMOTE is true, then the final
2100       products
2101       are copied into the repository.
2102     </big>
2103     <h4><big>pre_compilation</big></h4>
2104     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target executes the
2105       preconditions script
2106       to set up the compilation's output directories.
2107     </big>
2108     <h4><big>rebuild</big></h4>
2109     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target performs the actions of
2110       rebuilding.&nbsp;
2111       This mainly involves touching all of the files in SOURCE before the
2112       compilation
2113       has really started.
2114     </big>
2115     <h2><big><a name="CPP_SCRIPTS"></a><u>C++ Specific Files</u></big></h2>
2116     <h4><big>postconditions.sh</big></h4>
2117     <big>&nbsp;&nbsp;&nbsp;&nbsp; After a compilation has succeeded,
2118       the
2119       postconditions
2120       script performs the final actions required.&nbsp; The nature of these
2121       actions
2122       depends on the type of project being made.&nbsp; For a library project,
2123       the script copies the headers to the project's include directory and
2124       copies
2125       libraries to the appropriate locations.&nbsp; For application and test
2126       program targets, the script copies the final products to the
2127       appropriate
2128       repository directory.
2129     </big>
2130     <h4><big>preconditions.sh</big></h4>
2131     <big>&nbsp;&nbsp;&nbsp;&nbsp; Before any targets are compiled, the
2132       preconditions
2133       script ensures that the appropriate output directories exist for the
2134       project.&nbsp;
2135       The script also calls the version utilities to update the project's
2136       version
2137       file and to create any required resource files.<br>
2138     </big>
2139     <h4><big>rebuild_oldies.sh</big></h4>
2140     <big>&nbsp;&nbsp;&nbsp; &nbsp;Used for compilers that support
2141       multiple code
2142       files
2143       in one invocation. &nbsp;This is launched to compile a batch of sources
2144       and
2145       catch any errors.<br>
2146     </big>
2147     <hr noshade="noshade" size="8" width="100%">
2148     <center><small></small>
2149       <h2><big><a name="EXAMPLES"></a>CLAM Example Makefiles</big></h2>
2150       <small></small></center>
2151     <big>&nbsp;&nbsp;&nbsp;&nbsp; These examples show some common
2152       patterns for
2153       how&nbsp; is used.&nbsp; The makefiles below are actually used in real
2154       software
2155       projects.
2156     </big>
2157     <h3><big>Library-Only Makefile</big></h3>
2158     <big>This example creates a dynamic library.
2159     </big>
2160     <ul>
2161       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2162       </small>
2163       <p><big><tt>PROJECT = mechanisms</tt><br>
2164           <tt>TYPE = library</tt> <br>
2165           <tt>SOURCE = delayer.cpp eventmgr.cpp event_po.cpp heartbea.cpp
2166             instance.cpp
2167             \</tt> <br>
2168           <tt>&nbsp; libmain.cpp monitor.cpp semaphor.cpp state_ma.cpp
2169             timer.cpp
2170             time_sta.cpp</tt> <br>
2171           <tt>TARGETS = mechanisms.dll</tt> <br>
2172           <tt>LOCAL_LIBS_USED = basis</tt> <br>
2173           <tt>DEFINITIONS += BUILD_MECHANISMS USE_FEISTY_MEOW_DLLS</tt> </big></p>
2174       <small> </small><big> </big><small> </small>
2175       <p><big><tt>include cpp/rules.def</tt></big></p>
2176       <small> </small><small></small>
2177     </ul>
2178     <big>The dynamic library created here is mechanisms.dll.&nbsp; The
2179       basis
2180       library is linked
2181       in also.&nbsp; The file "roller.cpp" will also be copied to the build
2182       directory's
2183       include path, presumably since it is a template code file.
2184     </big>
2185     <h3><big>Library Plus Executable Makefile</big></h3>
2186     <big>This example shows the basis makefile with a couple of test
2187       programs
2188       also
2189       being generated.
2190     </big>
2191     <ul>
2192       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2193       </small>
2194       <p><big><tt>PROJECT = basis</tt> <br>
2195           <tt>TYPE = library</tt> <br>
2196           <tt>SOURCE = chaos.cpp checkup.cpp guards.cpp \</tt> <br>
2197           <tt>&nbsp; istring.cpp itime.cpp logger.cpp matrix.cpp
2198             portable.cpp \</tt> <br>
2199           <tt>&nbsp; realtime.cpp textdump.cpp timezone.cpp utility.cpp \</tt> <br>
2200           <tt>&nbsp; version_checker.cpp version_record.cpp</tt> <br>
2201           <tt>TARGETS = basis.lib t_string.exe t_alloc.exe</tt> </big></p>
2202       <small> </small><big> </big><small> </small>
2203       <p><big><tt>include cpp/rules.def</tt></big></p>
2204       <small> </small><small></small>
2205     </ul>
2206     <big>Note that the executables
2207       "t_string.exe" and "t_alloc.exe" require files called "t_string.cpp"
2208       and
2209       "t_alloc.cpp" to exist.&nbsp; These files are expected to contain the
2210       "main()"
2211       or "WinMain()" functions (or the MFC application object).&nbsp; All of
2212       the
2213       files in the SOURCE variable will be included in each final executable.
2214     </big>
2215     <h3><big>Executable-Only Makefile</big></h3>
2216     <big>This example is produces several test programs that exercise
2217       the
2218       associated
2219       library.
2220     </big>
2221     <ul>
2222       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2223       </small>
2224       <p><big><tt>PROJECT = t_basis</tt> <br>
2225           <tt>TYPE = test</tt> <br>
2226           <tt>SOURCE = instance.cpp t_basis.rc</tt> <br>
2227           <tt>TARGETS = t_alloc.exe t_chaos.exe t_checku.exe t_dattim.exe \</tt>
2228           <br>
2229           <tt>&nbsp; t_matrix.exe t_sequen.exe t_sorts.exe t_string.exe \</tt> <br>
2230           <tt>&nbsp; t_texdmp.exe</tt> <br>
2231           <tt>LOCAL_LIBS_USED = basis</tt> </big></p>
2232       <small> </small><big> </big><small> </small>
2233       <p><big><tt>include cpp/rules.def</tt></big></p>
2234       <small> </small><small></small>
2235     </ul>
2236     <big>The programs "t_alloc.exe" and so on will require C++ files
2237       with the
2238       same
2239       prefix (t_alloc.cpp) to contain the main program (as in the previous
2240       example).&nbsp;
2241       The items in the SOURCE list will be included in each executable, and
2242       the
2243       basis library will be linked in.
2244     </big>
2245     <h2><big><a name="CLAM_HINTS"></a>CLAM Hints</big></h2>
2246     <big>&nbsp;&nbsp;&nbsp;&nbsp; This section
2247       is devoted to untangling snags that have been encountered in the
2248       past.&nbsp;
2249       Hopefully problems you encounter will be discussed here. &nbsp;Please
2250       contribute
2251       any new problems found to the <a href="#lib_manager">library
2252         administrator</a>.
2253     </big>
2254     <h3><big>Problem:</big></h3>
2255     <big>&nbsp;&nbsp;&nbsp;&nbsp; A message like:
2256     </big>
2257     <ul>
2258       <small> </small><big> </big><small> </small>
2259       <ul>
2260         <small> </small><big>make: *** No rule to make target
2261           `o:/x86_w32_rel/project/final/myproj.dll',
2262           needed by `all'.&nbsp; Stop. </big><small> </small>
2263       </ul>
2264       <small> </small><small></small>
2265     </ul>
2266     <big>is displayed during a make.
2267     </big>
2268     <h3><big>Solution:</big></h3>
2269     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent reason for
2270       receiving a
2271       message
2272       similar to the above is that there is a file listed in SOURCE that
2273       either
2274       does not exist or that is capitalized differently from how it is
2275       listed.&nbsp;
2276       Check that all the files in SOURCE are in the makefile's directory and
2277       that the exact spelling of those files (including their case) is
2278       correct.
2279       <br>
2280       &nbsp;&nbsp;&nbsp;&nbsp; Another potential cause of this problem is
2281       if a file is included in the SOURCE that&nbsp; does not
2282       recognize.&nbsp;
2283       The standard compilable files are supported (*.cpp, *.c, *.rc), but it
2284       is possible that a makefile must handle a non-standard extension (such
2285       as *.idl).&nbsp; Either the user's makefile must supply a rule for
2286       processing
2287       this type of file or the user must negotiate with the&nbsp;
2288       administrator
2289       to get that type of target added to the&nbsp; support.
2290     </big>
2291     <h3><big>Problem:</big></h3>
2292     <big>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Clam is complaining about programs
2293       not being
2294       found
2295       during a build.
2296     </big>
2297     <h3><big>Solution:</big></h3>
2298     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent cause of this
2299       problem is a
2300       directory
2301       not being on your path.&nbsp; The compilation tools bin (CLAM_BINARIES)
2302       directory must be in
2303       the PATH variable.
2304       <br>
2305       &nbsp;&nbsp;&nbsp;&nbsp; Problems are occasionally seen when the PATH
2306       contains directory names that have spaces in them.&nbsp; Try using the
2307       shorter 8.3 form of the directory name.
2308       <br>
2309       &nbsp;&nbsp;&nbsp;&nbsp; An even more obscure situation sometimes
2310       occurs: paths with networked drives seem to somehow hide paths with
2311       local drives that
2312       are listed later in the PATH variable.&nbsp; The cause of this is
2313       unknown,
2314       although it was thought to be caused by NetWare at one point.&nbsp; To
2315       fix
2316       the situation, move the local paths before the networked ones.<br>
2317       <br>
2318     </big>
2319     <hr noshade="noshade" size="8" width="100%">
2320     <center><small></small>
2321       <h2><big><a name="ACKS"></a>Acknowledgements</big></h2>
2322       <small></small></center>
2323     <center><big>Thanks to April Bly Monnen for the wonderful cover
2324         art.
2325       </big><small></small>
2326       <p><big>Thanks to Kevin Wika for some early help with makefiles.
2327         </big></p>
2328       <small></small><big><big>
2329         </big></big><small></small>
2330       <hr noshade="noshade" size="8" width="100%"></center>
2331     <big><br>
2332       <br>
2333     </big>
2334   </body>
2335 </html>