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