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 choice.&nbsp; The current possibilities include
1467       GNU_LINUX, GNU_WINDOWS, and GNU_DARWIN.
1468     </big>
1469     <h4><big>COMPILER_FLAGS</big></h4>
1470     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the list of flags passed to
1471       the
1472       preprocessor
1473       and compiler. It is composed of the SYSTEM, the DEFINITIONS, the
1474       SEARCH_DIRS,
1475       and any user-included options. If flags that don't fit one of the
1476       categories
1477       are needed, they can be added here.
1478     </big>
1479     <h4><big>CONSOLE_MODE</big></h4>
1480     <big>&nbsp;&nbsp;&nbsp;&nbsp; This causes the program
1481       to be generated as a console application.&nbsp; This is relevant in
1482       systems
1483       (such as win32) where programs have a split personality depending on
1484       whether
1485       they are to have graphical user interfaces or just console interfaces.
1486     </big>
1487     <h4><big>DEBUG_FLAGS</big></h4>
1488     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are flags used for generating
1489       specialized
1490       versions of object files, such as ones that include debugging code
1491       (e.g.,
1492       for gdb) or ones that add code for profiling (e.g., gprof). Possible
1493       values
1494       in the Sun CenterLine Compiler environment are -g for debugging code
1495       and
1496       -pg for profiling.
1497     </big>
1498     <h4><big>DEFINITIONS</big></h4>
1499     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of compiler flags
1500       that define
1501       the
1502       value of C or C++ macros. These usually have the format of
1503       ?-D&lt;flag&gt;?,
1504       but in this particular variable only the &lt;flag&gt; itself should be
1505       listed
1506       (because the compiler option characters ?-D? are added automatically).
1507     </big>
1508     <h4><big>DEPENDENCY_ADDITIONS</big></h4>
1509     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of extra flags that
1510       gets passed
1511       to the auto-dependency tool.&nbsp; The list can vary for each compiler.
1512     </big>
1513     <h4><big>DEPS_FILE</big></h4>
1514     <big>&nbsp;&nbsp;&nbsp;&nbsp; This file is where the
1515       auto-dependency
1516       information
1517       is stored.&nbsp; The "makedep" program is used to generate
1518       auto-dependency
1519       information for the files listed in SOURCE.&nbsp; During a build, the
1520       DEPS_FILE
1521       is pulled into the actual code of the makefile; this causes the
1522       dependencies
1523       to be automatically included so that they can dictate the files that
1524       need
1525       to be rebuilt.
1526     </big>
1527     <h4><big>EXTRA_VERSIONS</big></h4>
1528     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of version files that
1529       also need
1530       to be updated to the main build version during a compilation.&nbsp;
1531       These
1532       are usually needed if a project compiles several executable files, and
1533       each one performs version checking.&nbsp; By default, any project
1534       containing
1535       a file called "version.ini" will get a version stamp from the main
1536       build
1537       version.
1538     </big>
1539     <h4><big>LIBRARIAN_FLAGS</big></h4>
1540     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of flags that are
1541       passed to the
1542       library creation tool.&nbsp; Sometimes this must be overridden for a
1543       particular
1544       compiler.
1545     </big>
1546     <h4><big>LIBS_USED</big></h4>
1547     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are code libraries that the
1548       executables
1549       depend upon.&nbsp; They are searched for in any of the directories
1550       listed
1551       in the LIBRARY_SEARCH_PATH.
1552     </big>
1553     <h4><big>LOAD_FLAG_PREFIX &amp; LOAD_FLAG_SUFFIX</big></h4>
1554     <big>&nbsp;&nbsp;&nbsp;&nbsp; These tell the linker and loader how
1555       to deal
1556       with
1557       the files and where to locate library components. The prefix is listed
1558       on the compilation command line before the object files are listed, and
1559       the suffix after. The prefix should contain information such as the
1560       directories
1561       to be searched for code libraries (although they should be added to
1562       LIBRARY_SEARCH_PATH).&nbsp;
1563       In the suffix definition, actual library loading statements (like
1564       -lmath)
1565       can be included (although they should be listed in a different form in
1566       LIBS_USED or LOCAL_LIBS_USED).
1567     </big>
1568     <h4><big>LOCAL_LIBS_USED</big></h4>
1569     <big>&nbsp;&nbsp;&nbsp;&nbsp; The names in this list actually
1570       cause the
1571       OBJECTS
1572       to be recompiled when the libraries listed have changed.&nbsp; To
1573       accomplish
1574       this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather
1575       than
1576       at some arbitrary place on the LIBRARY_SEARCH_PATH.&nbsp; These
1577       libraries
1578       also must follow the special naming convention followed by ; if
1579       "basis"
1580       is an entry in this list, then a library called "basis.lib" will be
1581       sought
1582       during the build.
1583     </big>
1584     <h4><big>NO_COMPILE</big></h4>
1585     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies that no compilation
1586       should be performed. &nbsp;Nothing in the SOURCE or TARGETS macros will
1587       be
1588       built.<br>
1589     </big>
1590     <h4><big>NO_DEPS</big></h4>
1591     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is an exclusion flag.&nbsp; If
1592       it is
1593       defined,
1594       then no auto-dependency files will be generated.&nbsp; This is useful
1595       if
1596       you're missing the makedep tool and trying to compile it.<br>
1597     </big>
1598     <h4><big>OBJECTS</big></h4>
1599     <big>&nbsp;&nbsp;&nbsp;&nbsp; The OBJECTS are all those files that
1600       need to
1601       be
1602       created during compilation.&nbsp; Usually this list is filled based on
1603       the files in SOURCE.
1604     </big>
1605     <h4><big>OPTIMIZE</big></h4>
1606     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create optimized
1607       code.&nbsp;
1608       The default optimization is for speed.
1609     </big>
1610     <h4><big>REBUILD</big></h4>
1611     <big>&nbsp;&nbsp;&nbsp;&nbsp; If the REBUILD variable is
1612       non-empty, then all
1613       files listed in the SOURCE variable are touched.&nbsp; This should
1614       cause
1615       all of those files to be rebuilt during the compilation.&nbsp;
1616       Occasionally
1617       GNU make will complain that a file is newer than the current time, but
1618       this does not usually cause any problems.
1619     </big>
1620     <h4><big>SOURCE</big></h4>
1621     <big>&nbsp;&nbsp;&nbsp;&nbsp; The SOURCE variable is a list of
1622       files that
1623       are
1624       to be compiled in order to create the final products of the
1625       project.&nbsp;
1626       These can be C++ source files (*.cpp), Win32 resource files (*.rc)
1627       and
1628       other types of source files.&nbsp; The list of objects to create will
1629       be
1630       determined by transforming the list of SOURCE files (such as by turning
1631       a file called "fud.cpp" into an object called "fud.obj").&nbsp; More
1632       file
1633       types will be added as they are needed.
1634     </big>
1635     <h4><big>STATIC</big></h4>
1636     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create statically
1637       linked
1638       targets.&nbsp;
1639       Executables or dynamic libraries will not link in any compiler supplied
1640       dynamic libraries, nor will they require them during run-time.
1641     </big>
1642     <h4><big>TYPE</big></h4>
1643     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a variable that describes
1644       the kind of
1645       project that is being compiled.&nbsp; Knowing the type of project is
1646       necessary
1647       because it controls some elements of the compilation and also of the
1648       final
1649       promotion of the compiled products.&nbsp; There are three TYPEs
1650       supported
1651       so far:
1652     </big>
1653     <ul>
1654       <small> </small><big> </big><small> </small>
1655       <li><big>library: indicates that the project will be primarily
1656           creating
1657           static
1658           or
1659           dynamic libraries.</big></li>
1660       <small> </small><big> </big><small> </small>
1661       <li><big>application: indicates that the project will create
1662           executables.</big></li>
1663       <small> </small><big> </big><small> </small>
1664       <li><big>test: indicates that the project constructs test
1665           programs.</big></li>
1666       <small> </small><small></small>
1667     </ul>
1668     <big>Projects of the "library" type will follow the special&nbsp;
1669       rules for
1670       their include directory (which is created as a copy of headers in the
1671       library
1672       directory).&nbsp; Library projects will also have their final products
1673       copied to the lib or dll subdirectories of the build directory being
1674       created.&nbsp;
1675       Projects that are "application"s will have their executables copied to
1676       the executable directory in the build.&nbsp; And "test" projects will
1677       be
1678       promoted to a subdirectory named after the PROJECT that resides under
1679       the
1680       test hierarchy in the build.
1681     </big>
1682     <h2><big><a name="DIRECTORY_VARS"></a><u>C++ Directory Structure
1683           Variables</u></big></h2>
1684     <h4><big>BASE_OUTPUT_PATH</big></h4>
1685     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is the parent directory
1686       for object files generated for the specified type of CPU and the style
1687       of
1688       build (e.g. debug or release builds).<br>
1689     </big>
1690     <h4><big>CPU_BUILD_DIR</big></h4>
1691     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable can be used to
1692       distinguish
1693       directory
1694       names used for output.&nbsp; It includes the cpu name and the type of
1695       build.
1696     </big>
1697     <h4><big>DYNAMIC_LIBRARY_DIR</big></h4>
1698     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where dynamic
1699       libraries will be
1700       stored after creation.<br>
1701     </big>
1702     <h4><big>EXECUTABLE_DIR</big></h4>
1703     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where executable files
1704       will be
1705       stored after creation.<br>
1706     </big>
1707     <h4><big>FINAL_DIR</big></h4>
1708     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the directory
1709       where the
1710       finished
1711       compilation products are stored, currently only import libraries for
1712       dynamic libraries.&nbsp;
1713       It is usually a directory under the OUTPUT_PATH named "final".
1714     </big>
1715     <h4><big>HEADER_SEARCH_PATH</big></h4>
1716     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1717       will be
1718       searched
1719       for C++ header files (files ending in ?.h?).
1720     </big>
1721     <h4><big>HOOPLE_HEADERS</big></h4>
1722 <big>DEPRECATED</big>
1723     <big>&nbsp;&nbsp;&nbsp;&nbsp; The two standard places to look for
1724       headers
1725       (the repository and the third party directory) are listed in this
1726       variable.
1727     </big>
1728     <h4><big>HOOPLE_LIBRARIES</big></h4>
1729 <big>DEPRECATED</big>
1730     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where our libraries are
1731       located.&nbsp; It is usually a subdirectory called "lib" under the
1732       repository
1733       directory.
1734     </big>
1735     <h4><big>LIBRARY_SEARCH_PATH</big></h4>
1736     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1737       will be
1738       searched
1739       for C++ library archives (files ending in ".a" or ".lib").
1740     </big>
1741     <h4><big>LOCAL_HEADERS</big></h4>
1742     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable provides a way to
1743       include
1744       headers
1745       prior to the default locations in the search path.&nbsp; For example,
1746       if
1747       you are compiling locally and have some headers that are not present in
1748       the build you are using, then you can specify where they are in this
1749       variable.
1750     </big>
1751     <h4><big>LOCAL_LIBRARIES</big></h4>
1752     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable allows other library
1753       directories
1754       to be added prior to the default search locations.&nbsp; This enables
1755       substitute
1756       static or import libraries to be used instead of the standard ones
1757       present
1758       in the build.
1759     </big>
1760     <h4><big>STATIC_LIBRARY_DIR</big></h4>
1761     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the location where code
1762       libraries are
1763       to be copied during promotion and where they are to be searched for
1764       when
1765       listed in LOCAL_LIBS_USED.&nbsp; Under Unix, these libraries have a
1766       ?.a?
1767       suffix and are created with the "ar" program.&nbsp; Under Win32,
1768       these
1769       libraries have a ?.lib? suffix and are created with "link".
1770     </big>
1771     <h4><big>OBJECT_DIR</big></h4>
1772     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where object files will be
1773       stored
1774       during
1775       compilation for the target type being produced.
1776     </big>
1777     <h4><big>OUTPUT_DIRECTORY_LIST</big></h4>
1778     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1779       need to be
1780       created under the OUTPUT_PATH.&nbsp; It contains the "final" directory
1781       where all finished products are stored, as well as all the intermediate
1782       directories for objects.
1783     </big>
1784     <h4><big>OUTPUT_PATH</big></h4>
1785     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the temporary file storage
1786       area.&nbsp;
1787       Any files that are created during the compilation process will be
1788       stored
1789       under here in a subdirectory named after the PROJECT.
1790     </big>
1791     <h4><big>OUTPUT_ROOT</big></h4>
1792     <big>&nbsp;&nbsp;&nbsp;&nbsp; This specifies the root portion of
1793       the
1794       OUTPUT_PATH.&nbsp;
1795       It lets a PC build use drive letters for the root, while a Unix build
1796       can
1797       specify a directory hierarchy.
1798     </big>
1799     <h4><big>SEARCH_DIRS</big></h4>
1800     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1801       will be
1802       searched
1803       for both C++ header files and for C++ code libraries.&nbsp; The items
1804       placed
1805       on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the
1806       HEADER_SEARCH_PATH.&nbsp;
1807       The reasoning behind this variable is lost in antiquity.
1808     </big>
1809     <h4><big>TESTS_DIR <br>
1810       </big></h4>
1811     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where test programs
1812       will be
1813       stored after creation.<br>
1814     </big>
1815     <h4><big>THIRD_PARTY_DIR</big></h4>
1816     <big>&nbsp;&nbsp;&nbsp;&nbsp; Third party components are sometimes
1817       used in
1818       the
1819       creation of products.&nbsp; The directory is expected to have a
1820       structure
1821       containing "include" and "lib" subdirectories where headers and
1822       libraries
1823       are stored.
1824     </big>
1825     <h2><big><a name="CPP_FLAGS"></a><u>Compiler Dependent Flags</u></big></h2>
1826     <h4><big>
1827         CC</big></h4>
1828     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the C++ compiler
1829       executable.
1830     </big>
1831     <h4><big>COMPILER_HEADER_DIR</big></h4>
1832     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the compiler's header
1833       (or
1834       include)
1835       root directory is located.&nbsp; It is usually based on the root
1836       directory.
1837     </big>
1838     <h4><big>COMPILER_LIBRARY_DIR</big></h4>
1839     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the code libraries for
1840       the
1841       compiler
1842       are located.&nbsp; It is usually based on the root directory.
1843     </big>
1844     <h4><big>COMPILER_ROOT_DIR</big></h4>
1845     <big>&nbsp;&nbsp;&nbsp;&nbsp; This should automatically be set to
1846       the
1847       appropriate
1848       local directory where the C++ compiler is located.
1849     </big>
1850     <h4><big>CREATE_LIBRARY_FLAG</big></h4>
1851     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag, if required, specifies
1852       the text
1853       that
1854       must precede the name of a library to create.&nbsp; It is passed to the
1855       library creation tool.
1856     </big>
1857     <h4><big>DEF_FILE</big></h4>
1858     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Win32
1859       programs.&nbsp;
1860       It specifies the name of a DEF file for all of the products created in
1861       the project.
1862     </big>
1863     <h4><big>LIB_PREFIX &amp; LIB_SUFFIX</big></h4>
1864     <big>&nbsp;&nbsp;&nbsp; &nbsp;The portions of a library's name
1865       dictated by the operating system. &nbsp;For example, on Unix the prefix
1866       is "lib"
1867       and the suffix is ".a", leading to library names like "libbasis.a" for
1868       the
1869       basis library. &nbsp;On win32, the prefix is "" and the suffix is
1870       ".lib", leading
1871       to library names like "basis.lib".<br>
1872     </big>
1873     <h4><big>LIBRARY_NAME_FLAG</big></h4>
1874     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag contains the text that
1875       specifies a
1876       library
1877       that will be included in a link.&nbsp; It is often "-l".
1878     </big>
1879     <h4><big>LIBRARY_PATH_FLAG</big></h4>
1880     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag provides the text needed
1881       to add
1882       another
1883       library search path.&nbsp; Multiple occurrences of this flag followed
1884       by
1885       a directory name are allowed by most compilers.
1886     </big>
1887     <h4><big>LIBRARY_TOOL</big></h4>
1888     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program
1889       responsible
1890       for
1891       creating libraries.
1892     </big>
1893     <h4><big>LINK_TOOL</big></h4>
1894     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program that
1895       links.&nbsp;
1896       This is sometimes the same as the compiler (CC) and sometimes the same
1897       as the librarian (LIBRARY_TOOL).
1898     </big>
1899     <h4><big>LINKER_OPTION_SEPARATOR</big></h4>
1900     <big>&nbsp;&nbsp;&nbsp;&nbsp; In some compilers, linker options
1901       need to be
1902       separated
1903       from compiler options that occur on the same command line.&nbsp; This
1904       flag
1905       serves that purpose.
1906     </big>
1907     <h4><big>LINKER_OUTPUT_FLAG</big></h4>
1908     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is sometimes required by a
1909       linker
1910       for
1911       specifying the name of the library or executable that it is creating.
1912     </big>
1913     <h4><big>OBJECT_NAME_FLAG</big></h4>
1914     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is used to specify the
1915       name of an
1916       object
1917       file being created.&nbsp; It is passed to the compiler to override
1918       whatever
1919       default name would be used.
1920     </big>
1921     <h2><big><u><a name="vcpp_only"></a>Microsoft-Visual C++ Only</u><br>
1922       </big></h2>
1923     <h4><big>USE_MFC</big></h4>
1924     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Visual C++
1925       and
1926       indicates
1927       that MFC is to be used in creating this project.&nbsp; This is usually
1928       the case for GUI applications.
1929     </big>
1930     <h4><big>VC_ROOT</big></h4>
1931     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is an override that allows the
1932       compiler
1933       root
1934       directory to be customized without changing the&nbsp; code.&nbsp; If
1935       VC_ROOT
1936       is set (either in a makefile or as an external variable), then it will
1937       be used in place of the COMPILER_ROOT_DIR.&nbsp; The best way to use
1938       this
1939       override is as an external environment variable; this allows makefiles
1940       to remain the same despite your local configuration of the compiler.
1941       <br>
1942       &nbsp;&nbsp;&nbsp;&nbsp; Note that this variable should use
1943       forward-slashes,
1944       where DOS/Win32 would use backslashes.&nbsp; Also, if you have
1945       installed
1946       Visual C++ in a directory path containing space characters, then please
1947       use the 8.3 notation for the directories containing the spaces; this
1948       allows
1949       the name to be passed around successfully.&nbsp; For example...
1950     </big>
1951     <center><small></small><big> </big><big> </big><big> </big><big> </big><big></big><big></big><big>
1952       </big><big> </big><big> </big><big> </big><big>
1953       </big><big> </big><big> </big><big> </big><small> </small><small></small><small>
1954       </small><small> </small><small> </small><small> </small><small>
1955       </small><small> </small><small> </small><small> </small><small> </small><small></small><small>
1956       </small><small> </small><small> </small><small> </small>
1957       <table cellpadding="8" cellspacing="4">
1958         <tbody>
1959           <tr>
1960             <td><big> </big><small> </small>
1961               <center><big><u>If Visual C++ Is Installed In</u></big></center>
1962               <small> </small><big> </big></td>
1963             <td><big> </big><small> </small>
1964               <center><big><u>Then VC_ROOT Should Be</u></big></center>
1965               <small> </small><big> </big></td>
1966           </tr>
1967           <tr>
1968             <td><big> </big><small> </small>
1969               <center><big>c:\devstudio\vc</big></center>
1970               <small> </small><big> </big></td>
1971             <td><big> </big><small> </small>
1972               <center><big>c:/devstudio/vc</big></center>
1973               <small> </small><big> </big></td>
1974           </tr>
1975           <tr>
1976             <td><big> </big><small> </small>
1977               <center><big>c:\program files\devstudio\vc</big></center>
1978               <small> </small><big> </big></td>
1979             <td><big> </big><small> </small>
1980               <center><big>c:/progra~1/devstudio/vc</big></center>
1981               <small> </small><big> </big></td>
1982           </tr>
1983         </tbody>
1984       </table>
1985       <small></small></center>
1986     <h4><big>VCS_ROOT</big></h4>
1987     <big>&nbsp;&nbsp;&nbsp;&nbsp; Similarly to the VC_ROOT, this
1988       variable points
1989       at the root of the C# support for Visual Studio.Net.<br>
1990     </big>
1991     <h4><big>FRAMEWORK_DIR</big></h4>
1992     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable specifies the location
1993       of the
1994       .Net framework directory.&nbsp; On MS-Windows XP, the default should be
1995       fine.&nbsp; For MS-Windows 2000 or other Win32 OSes, the windows
1996       directory
1997       should be "winnt" instead.&nbsp; If the operating system is configured
1998       in a non-default way, the framework directory can be specified in an
1999       environment variable.<br>
2000     </big>
2001     <h4><big>VCPP_USE_BASE</big></h4>
2002     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that standard Win32
2003       libraries should
2004       be linked in.<br>
2005     </big>
2006     <h4><big>VCPP_USE_GUI</big></h4>
2007     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MFC libraries
2008       should be
2009       linked in.
2010     </big>
2011     <h4><big>VCPP_USE_OLE</big></h4>
2012     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the COM / OLE
2013       libraries should
2014       be linked in.
2015     </big>
2016     <h4><big>VCPP_USE_RPC</big></h4>
2017     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-RPC libraries
2018       should be
2019       linked in.<br>
2020     </big>
2021     <h4><big>VCPP_USE_SOCK</big></h4>
2022     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-WinSock
2023       libraries should
2024       be linked in.<br>
2025     </big>
2026     <h2><big><a name="CPP_RULES"></a><u>C++ Specific Rules</u></big></h2>
2027     <big>&nbsp;&nbsp;&nbsp;&nbsp; These types of targets have one
2028       thing in
2029       common;
2030       if any of the items that a target depends on in SOURCE or
2031       LOCAL_LIBS_USED
2032       or included files or whatever have changed since the last time the
2033       target
2034       was created, then it is recompiled.
2035     </big>
2036     <h4><big>%.bad</big></h4>
2037     <big>&nbsp;&nbsp;&nbsp; &nbsp;Causes the make to die. &nbsp;This
2038       is added when an incorrect file type is spotted in a list of targets.<br>
2039     </big>
2040     <h4><big>%.dll</big></h4>
2041     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create dynamically linked
2042       libraries from
2043       the SOURCE.
2044     </big>
2045     <h4><big>%.elf</big></h4>
2046     <big>&nbsp;&nbsp;&nbsp; &nbsp;Creates elf-formatted binaries for
2047       use with a
2048       firmware build (a specialized RTOS is the only one currently supported).<br>
2049     </big>
2050     <h4><big>%.exe</big></h4>
2051     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates an executable program
2052       using all
2053       of
2054       the objects and libraries specified.&nbsp; It is therefore important in
2055       a&nbsp; makefile to only have executables that depend on the same group
2056       of object files.&nbsp; The hidden agenda in the "exe" type of target is
2057       that a file ending in ".cpp" must exist; this is taken as the root of
2058       the
2059       executable.&nbsp; It should usually contain the main() function (or its
2060       equivalent).
2061     </big>
2062     <h4><big>%.lib</big></h4>
2063     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates static libraries from
2064       the files
2065       listed
2066       in OBJECTS.
2067     </big>
2068     <h4><big>%.nil</big></h4>
2069     <big>&nbsp;&nbsp;&nbsp; &nbsp;A blank target for test compiles.<br>
2070     </big>
2071     <h4><big>%.obj</big></h4>
2072     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create object files from C++
2073       source
2074       files
2075       (files ending in .c or .cpp).
2076     </big>
2077     <h4><big>%.res</big></h4>
2078     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create compiled resource files
2079       from RC
2080       files
2081       in the SOURCE list.
2082     </big>
2083     <h2><big><a name="CPP_TARGETS"></a><u>C++ Specific Targets</u></big></h2>
2084     <h4><big>
2085         check_requirements</big></h4>
2086     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target ensures that certain
2087       characteristics
2088       of the makefile are present.&nbsp; It complains and aborts the make if
2089       they are missing.
2090     </big>
2091     <h4><big>post_compilation</big></h4>
2092     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target finalizes the
2093       compilation by
2094       running
2095       the postconditions script.&nbsp; If PROMOTE is true, then the final
2096       products
2097       are copied into the repository.
2098     </big>
2099     <h4><big>pre_compilation</big></h4>
2100     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target executes the
2101       preconditions script
2102       to set up the compilation's output directories.
2103     </big>
2104     <h4><big>rebuild</big></h4>
2105     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target performs the actions of
2106       rebuilding.&nbsp;
2107       This mainly involves touching all of the files in SOURCE before the
2108       compilation
2109       has really started.
2110     </big>
2111     <h2><big><a name="CPP_SCRIPTS"></a><u>C++ Specific Files</u></big></h2>
2112     <h4><big>postconditions.sh</big></h4>
2113     <big>&nbsp;&nbsp;&nbsp;&nbsp; After a compilation has succeeded,
2114       the
2115       postconditions
2116       script performs the final actions required.&nbsp; The nature of these
2117       actions
2118       depends on the type of project being made.&nbsp; For a library project,
2119       the script copies the headers to the project's include directory and
2120       copies
2121       libraries to the appropriate locations.&nbsp; For application and test
2122       program targets, the script copies the final products to the
2123       appropriate
2124       repository directory.
2125     </big>
2126     <h4><big>preconditions.sh</big></h4>
2127     <big>&nbsp;&nbsp;&nbsp;&nbsp; Before any targets are compiled, the
2128       preconditions
2129       script ensures that the appropriate output directories exist for the
2130       project.&nbsp;
2131       The script also calls the version utilities to update the project's
2132       version
2133       file and to create any required resource files.<br>
2134     </big>
2135     <h4><big>rebuild_oldies.sh</big></h4>
2136     <big>&nbsp;&nbsp;&nbsp; &nbsp;Used for compilers that support
2137       multiple code
2138       files
2139       in one invocation. &nbsp;This is launched to compile a batch of sources
2140       and
2141       catch any errors.<br>
2142     </big>
2143     <hr noshade="noshade" size="8" width="100%">
2144     <center><small></small>
2145       <h2><big><a name="EXAMPLES"></a>CLAM Example Makefiles</big></h2>
2146       <small></small></center>
2147     <big>&nbsp;&nbsp;&nbsp;&nbsp; These examples show some common
2148       patterns for
2149       how&nbsp; is used.&nbsp; The makefiles below are actually used in real
2150       software
2151       projects.
2152     </big>
2153     <h3><big>Library-Only Makefile</big></h3>
2154     <big>This example creates a dynamic library.
2155     </big>
2156     <ul>
2157       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2158       </small>
2159       <p><big><tt>PROJECT = mechanisms</tt><br>
2160           <tt>TYPE = library</tt> <br>
2161           <tt>SOURCE = delayer.cpp eventmgr.cpp event_po.cpp heartbea.cpp
2162             instance.cpp
2163             \</tt> <br>
2164           <tt>&nbsp; libmain.cpp monitor.cpp semaphor.cpp state_ma.cpp
2165             timer.cpp
2166             time_sta.cpp</tt> <br>
2167           <tt>TARGETS = mechanisms.dll</tt> <br>
2168           <tt>LOCAL_LIBS_USED = basis</tt> <br>
2169           <tt>DEFINITIONS += BUILD_MECHANISMS USE_FEISTY_MEOW_DLLS</tt> </big></p>
2170       <small> </small><big> </big><small> </small>
2171       <p><big><tt>include cpp/rules.def</tt></big></p>
2172       <small> </small><small></small>
2173     </ul>
2174     <big>The dynamic library created here is mechanisms.dll.&nbsp; The
2175       basis
2176       library is linked
2177       in also.&nbsp; The file "roller.cpp" will also be copied to the build
2178       directory's
2179       include path, presumably since it is a template code file.
2180     </big>
2181     <h3><big>Library Plus Executable Makefile</big></h3>
2182     <big>This example shows the basis makefile with a couple of test
2183       programs
2184       also
2185       being generated.
2186     </big>
2187     <ul>
2188       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2189       </small>
2190       <p><big><tt>PROJECT = basis</tt> <br>
2191           <tt>TYPE = library</tt> <br>
2192           <tt>SOURCE = chaos.cpp checkup.cpp guards.cpp \</tt> <br>
2193           <tt>&nbsp; istring.cpp itime.cpp logger.cpp matrix.cpp
2194             portable.cpp \</tt> <br>
2195           <tt>&nbsp; realtime.cpp textdump.cpp timezone.cpp utility.cpp \</tt> <br>
2196           <tt>&nbsp; version_checker.cpp version_record.cpp</tt> <br>
2197           <tt>TARGETS = basis.lib t_string.exe t_alloc.exe</tt> </big></p>
2198       <small> </small><big> </big><small> </small>
2199       <p><big><tt>include cpp/rules.def</tt></big></p>
2200       <small> </small><small></small>
2201     </ul>
2202     <big>Note that the executables
2203       "t_string.exe" and "t_alloc.exe" require files called "t_string.cpp"
2204       and
2205       "t_alloc.cpp" to exist.&nbsp; These files are expected to contain the
2206       "main()"
2207       or "WinMain()" functions (or the MFC application object).&nbsp; All of
2208       the
2209       files in the SOURCE variable will be included in each final executable.
2210     </big>
2211     <h3><big>Executable-Only Makefile</big></h3>
2212     <big>This example is produces several test programs that exercise
2213       the
2214       associated
2215       library.
2216     </big>
2217     <ul>
2218       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2219       </small>
2220       <p><big><tt>PROJECT = t_basis</tt> <br>
2221           <tt>TYPE = test</tt> <br>
2222           <tt>SOURCE = instance.cpp t_basis.rc</tt> <br>
2223           <tt>TARGETS = t_alloc.exe t_chaos.exe t_checku.exe t_dattim.exe \</tt>
2224           <br>
2225           <tt>&nbsp; t_matrix.exe t_sequen.exe t_sorts.exe t_string.exe \</tt> <br>
2226           <tt>&nbsp; t_texdmp.exe</tt> <br>
2227           <tt>LOCAL_LIBS_USED = basis</tt> </big></p>
2228       <small> </small><big> </big><small> </small>
2229       <p><big><tt>include cpp/rules.def</tt></big></p>
2230       <small> </small><small></small>
2231     </ul>
2232     <big>The programs "t_alloc.exe" and so on will require C++ files
2233       with the
2234       same
2235       prefix (t_alloc.cpp) to contain the main program (as in the previous
2236       example).&nbsp;
2237       The items in the SOURCE list will be included in each executable, and
2238       the
2239       basis library will be linked in.
2240     </big>
2241     <h2><big><a name="CLAM_HINTS"></a>CLAM Hints</big></h2>
2242     <big>&nbsp;&nbsp;&nbsp;&nbsp; This section
2243       is devoted to untangling snags that have been encountered in the
2244       past.&nbsp;
2245       Hopefully problems you encounter will be discussed here. &nbsp;Please
2246       contribute
2247       any new problems found to the <a href="#lib_manager">library
2248         administrator</a>.
2249     </big>
2250     <h3><big>Problem:</big></h3>
2251     <big>&nbsp;&nbsp;&nbsp;&nbsp; A message like:
2252     </big>
2253     <ul>
2254       <small> </small><big> </big><small> </small>
2255       <ul>
2256         <small> </small><big>make: *** No rule to make target
2257           `o:/x86_w32_rel/project/final/myproj.dll',
2258           needed by `all'.&nbsp; Stop. </big><small> </small>
2259       </ul>
2260       <small> </small><small></small>
2261     </ul>
2262     <big>is displayed during a make.
2263     </big>
2264     <h3><big>Solution:</big></h3>
2265     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent reason for
2266       receiving a
2267       message
2268       similar to the above is that there is a file listed in SOURCE that
2269       either
2270       does not exist or that is capitalized differently from how it is
2271       listed.&nbsp;
2272       Check that all the files in SOURCE are in the makefile's directory and
2273       that the exact spelling of those files (including their case) is
2274       correct.
2275       <br>
2276       &nbsp;&nbsp;&nbsp;&nbsp; Another potential cause of this problem is
2277       if a file is included in the SOURCE that&nbsp; does not
2278       recognize.&nbsp;
2279       The standard compilable files are supported (*.cpp, *.c, *.rc), but it
2280       is possible that a makefile must handle a non-standard extension (such
2281       as *.idl).&nbsp; Either the user's makefile must supply a rule for
2282       processing
2283       this type of file or the user must negotiate with the&nbsp;
2284       administrator
2285       to get that type of target added to the&nbsp; support.
2286     </big>
2287     <h3><big>Problem:</big></h3>
2288     <big>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Clam is complaining about programs
2289       not being
2290       found
2291       during a build.
2292     </big>
2293     <h3><big>Solution:</big></h3>
2294     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent cause of this
2295       problem is a
2296       directory
2297       not being on your path.&nbsp; The compilation tools bin (CLAM_BINARIES)
2298       directory must be in
2299       the PATH variable.
2300       <br>
2301       &nbsp;&nbsp;&nbsp;&nbsp; Problems are occasionally seen when the PATH
2302       contains directory names that have spaces in them.&nbsp; Try using the
2303       shorter 8.3 form of the directory name.
2304       <br>
2305       &nbsp;&nbsp;&nbsp;&nbsp; An even more obscure situation sometimes
2306       occurs: paths with networked drives seem to somehow hide paths with
2307       local drives that
2308       are listed later in the PATH variable.&nbsp; The cause of this is
2309       unknown,
2310       although it was thought to be caused by NetWare at one point.&nbsp; To
2311       fix
2312       the situation, move the local paths before the networked ones.<br>
2313       <br>
2314     </big>
2315     <hr noshade="noshade" size="8" width="100%">
2316     <center><small></small>
2317       <h2><big><a name="ACKS"></a>Acknowledgements</big></h2>
2318       <small></small></center>
2319     <center><big>Thanks to April Bly Monnen for the wonderful cover
2320         art.
2321       </big><small></small>
2322       <p><big>Thanks to Kevin Wika for some early help with makefiles.
2323         </big></p>
2324       <small></small><big><big>
2325         </big></big><small></small>
2326       <hr noshade="noshade" size="8" width="100%"></center>
2327     <big><br>
2328       <br>
2329     </big>
2330   </body>
2331 </html>