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_BINARY_DIR</big></h4>
 992     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a folder where the helper
 993       binaries for the CLAM makefile system are located.  <br>
 994     </big>
 995     <h4><big>CLAM_DIR</big></h4>
 996     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable points at the location
 997       where the&nbsp; definitions and helper scripts are located.&nbsp; The
 998       default is
 999       "~/yeti/clam",
1000       but this can be overridden for local installations of .<br>
1001     </big>
1002     <h4><big>CLAM_ERROR_SOUND</big></h4>
1003     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of sound files
1004       that should be played when a make stops with an error. &nbsp;It serves
1005       as
1006       an audible warning that something bad happened.<br>
1007     </big>
1008     <h4><big>CLAM_FINISH_SOUND</big></h4>
1009     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of sound files
1010       that should be played when the make has concluded
1011       successfully. &nbsp;It should play when the outer-most make
1012       has seen all targets created as intended.<br>
1013     </big>
1014     <h4><big>CLAM_TMP</big></h4>
1015     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies the location for temporary
1016       files generated during a make. &nbsp;The default value usually works
1017       fine.
1018       &nbsp;This directory will be created if it does not already exist.<br>
1019     </big>
1020     <h4><big>CLEANUPS</big></h4>
1021     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of files to be
1022       removed by the
1023       make
1024       clean command.&nbsp; They are possibly acquired from the TARGETS
1025       defined
1026       in the user's Makefile, or by language dependent rules for
1027       cleaning.&nbsp;
1028       Additional files can be added to this list by the user's makefile also.
1029     </big>
1030     <h4><big>DIRTY_FILE</big></h4>
1031     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable points at a file that
1032       signifies
1033       that some targets have been remade.&nbsp; It is not used at the base
1034       level
1035       of clam, but language-specific versions might do something special if
1036       targets
1037       were remade (such as put them in a build repository).
1038     </big>
1039     <h4><big>FAILURE_FILE</big></h4>
1040     <big>&nbsp;&nbsp;&nbsp;&nbsp; This file is used as a flag that
1041       indicates
1042       when
1043       a make has failed.&nbsp; The particular file used depends on the
1044       project
1045       name for this makefile.&nbsp; It is cleared at both the beginning and
1046       end
1047       of a make.
1048     </big>
1049     <h4><big>FIRST_TARGETS</big></h4>
1050     <big>&nbsp;&nbsp;&nbsp;&nbsp; The FIRST_TARGETS are made before
1051       any
1052       libraries
1053       are created and before any executables are compiled.&nbsp; There must
1054       be
1055       a rule for making every entry in this list, either through implicit
1056       rules
1057       or explicit ones provided by the user's makefile.
1058     </big>
1059     <h4><big>FLAG_FILES</big></h4>
1060     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of all the files
1061       that are used for compilation flags. &nbsp;They are whacked at the
1062       beginning
1063       and end of a make.<br>
1064     </big>
1065     <h4><big>HIDER</big></h4>
1066     <big>&nbsp;&nbsp;&nbsp;&nbsp; This macro is used throughout&nbsp;
1067       to hide the
1068       commands that are being sent to the operating system.&nbsp; It can be
1069       disabled to allow a verbose make (see the NOISY macro).
1070     </big>
1071     <h4><big>HIDESH</big></h4>
1072     <big>&nbsp;&nbsp;&nbsp;&nbsp; Just like HIDER, but this macro is
1073       specifically
1074       for launching shell scripts. &nbsp;Some versions of GNU make (like
1075       Cygwin's)
1076       have problems running scripts which don't arise when running executable
1077       files.
1078       &nbsp;Those problems led to the creation of the HIDESH macro for those
1079       specific
1080       cases. &nbsp;This is not an issue for Unix systems.
1081     </big>
1082     <h4><big>&nbsp;LAST_TARGETS</big></h4>
1083     <big>&nbsp;&nbsp;&nbsp;&nbsp; The LAST_TARGETS are made after all
1084       of the
1085       other
1086       standard targets are made.&nbsp; Their must be a rule for making every
1087       entry in this list, either through implicit rules or explicit ones
1088       provided
1089       by the user's makefile.
1090     </big>
1091     <h4><big>NOISY</big></h4>
1092     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable can be used to cause a
1093       verbose
1094       make.&nbsp;
1095       If the variable is non-empty, then all commands will be echoed to
1096       standard
1097       output.&nbsp; Otherwise, the default is to hide the commands that are
1098       issued
1099       and just show the output of running those commands.
1100     </big>
1101     <h4><big>OP_SYSTEM</big></h4>
1102     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a flag that defines the
1103       operating
1104       system
1105       name.&nbsp; This flag is sometimes used to choose the appropriate tools
1106       per platform or to conditionally compile code for system
1107       dependent interfaces.&nbsp; The available possibilities so far are
1108       UNIX,
1109       OS2, SYSV (System V Unix), DOS, and WIN32.&nbsp; Only UNIX and WIN32
1110       are
1111       currently very functional.
1112     </big>
1113     <h4><big>&nbsp;OTHER_CLEANS</big></h4>
1114     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are targets to execute before
1115       performing
1116       the main clean up during "make clean".&nbsp; These might be targets
1117       that
1118       contain shell commands to execute as part of clean up or they could
1119       contain
1120       the "clean_subdirs" command (defined below).
1121     </big>
1122     <h4><big>PROJECT</big></h4>
1123     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a variable that provides the
1124       name of
1125       the
1126       project being compiled.&nbsp; This should be a word that can also be
1127       used
1128       as a directory name and as a partial component of filenames.&nbsp;
1129       Thus, spaces
1130       and other unusual punctuation characters are discouraged.&nbsp; All of
1131       the project's temporary directories will be created based on this
1132       variable.
1133     </big>
1134     <h4><big>FEISTY_MEOW_DIR</big></h4>
1135     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies the root directory
1136       for compilation or other&nbsp; building activities. &nbsp; The
1137       repository
1138       is also where source code and final products of compilation reside,
1139       unless
1140       the default is over-ridden (see TARGETS_DIR).<br>
1141     </big>
1142     <h4><big>SH &amp; SHELL</big></h4>
1143     <big>&nbsp;&nbsp;&nbsp;&nbsp; These variables both point at a
1144       shell program
1145       that is
1146       used for starting commands. &nbsp;SHELL is defined by GNU make, whereas
1147       SH is defined by .
1148     </big>
1149     <h4><big>SUB_FLAG_FILES</big></h4>
1150     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a list of the compilation
1151       flag files
1152       which
1153       should be destroyed only at the end of a make.&nbsp; They are used for
1154       communication
1155       with submakefiles--makefiles that were invoked by "this" makefile.<br>
1156     </big>
1157     <h4><big>SUBMAKE_FLAG</big></h4>
1158     <big>&nbsp;&nbsp;&nbsp; &nbsp;This points to a file whose presence
1159       indicates
1160       that
1161       a "submake" performed some actions. &nbsp;The flag can be interpreted
1162       by
1163       some language-specific versions of&nbsp; as a reason to set a flag
1164       using
1165       the
1166       DIRTY_FILE.<br>
1167     </big>
1168     <h4><big>TARGETS</big></h4>
1169     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are the products to be created
1170       by .&nbsp;
1171       Each item listed in TARGETS should have a rule that knows how to create
1172       that type of file.&nbsp; The language independent system provides very
1173       few suffix based rules.&nbsp; TARGETS is filled in by the user in
1174       their&nbsp; file, but it is not used directly by the&nbsp;
1175       system.&nbsp;
1176       Instead,
1177       a generated variable called ACTUAL_TARGETS is used.<br>
1178     </big>
1179     <h4><big>TARGETS_DIR</big></h4>
1180     <big>&nbsp;&nbsp;&nbsp;&nbsp; This folder is where all generated
1181       files are
1182       to
1183       be stored. &nbsp;It is usually identical to FEISTY_MEOW_DIR but can be
1184       overridden
1185       when the targets should be stored elsewhere.<br>
1186     </big>
1187     <h4><big>Version components: major, minor, revision, build<br>
1188       </big></h4>
1189     <big>&nbsp;&nbsp;&nbsp; &nbsp;These four variables specify the
1190       version of
1191       this
1192       particular build. &nbsp;They are usually stored in the
1193       PARAMETER_FILE.
1194       &nbsp;The major and minor versions are the traditional 2.3, 4.0, etc
1195       style
1196       of release numbers. &nbsp;The revision number is often used to sequence
1197       the
1198       builds of that particular release, such that build 3.5.127 is the 127th
1199       build
1200       of the 3.5 release.<br>
1201       &nbsp; &nbsp; &nbsp;A version-tagged file (such as an executable or
1202       dynamic
1203       library) with any one of the major, minor or revision numbers differing
1204       from
1205       an installed build is incompatible with the installed build. &nbsp;An
1206       executable
1207       file or dynamic library will not be allowed to load other dynamic
1208       libraries
1209       where these numbers differ.<br>
1210       &nbsp; &nbsp; &nbsp;The last version component is misleadingly called
1211       "build";
1212       this number specifies the service pack level for a file. &nbsp;Files
1213       whose
1214       versions only differ in the last "build" component are intended to be
1215       compatible
1216       with each other. &nbsp;The understanding is that if only that number
1217       differs,
1218       then the external interface to the file has not changed, although the
1219       interior
1220       implementation may have.<br>
1221     </big>
1222     <h2><big><a name="LANG_INDEP_RULES"></a><u>Language Independent
1223           Rules</u></big></h2>
1224     <big>&nbsp;&nbsp;&nbsp;&nbsp; The file "$/rules.def" uses the
1225       composite
1226       macros
1227       defined in "$/variables.def" together with a set of make rules to
1228       perform
1229       actions during compilation.&nbsp; The rules file should be included in
1230       the user's Makefile after the compilation variables have been
1231       initialized
1232       for the project being compiled.&nbsp; The user's own targets should be
1233       placed after the directive that includes "$/rules.def".
1234     </big>
1235     <h4><big>%.halt</big></h4>
1236     <big>&nbsp;&nbsp;&nbsp;&nbsp; These targets cause&nbsp; to exit,
1237       usually to
1238       avoid
1239       something that it considers catastrophic.&nbsp; An example of this
1240       would
1241       be when&nbsp; finds an inappropriate entry in the list of objects to
1242       create;
1243       allowing a "make clean" on this makefile will delete files that are
1244       probably
1245       not intended.&nbsp; Hence, when&nbsp; finds this kind of usage, it will
1246       stop the make and issue a complaint.
1247     </big>
1248     <h4><big>%.make</big></h4>
1249     <big>&nbsp;&nbsp;&nbsp;&nbsp; Used to compile a makefile in a
1250       subdirectory
1251       named
1252       "%".&nbsp; This rule is employed by the BUILD_BEFORE macro, but can be
1253       used in the user's makefile targets also.
1254     </big>
1255     <h2><big><a name="LANG_INDEP_TARGETS"></a><u>Language Independent
1256           Targets</u></big></h2>
1257     <big>&nbsp;&nbsp;&nbsp; The following targets are defined by
1258       "$/rules.def".
1259     </big>
1260     <h4><big>all</big></h4>
1261     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a standard target that is
1262       executed
1263       when
1264       no particular target is specified at the make command line.&nbsp; It is
1265       an umbrella target that invokes all of the other targets required to
1266       perform
1267       a make.&nbsp; The order in which the major targets are created is:
1268     </big>
1269     <ol>
1270       <small> </small><big> </big><small> </small>
1271       <li><big>FIRST_TARGETS</big></li>
1272       <small> </small><big> </big><small> </small>
1273       <li><big>TARGETS</big></li>
1274       <small> </small><big> </big><small> </small>
1275       <li><big>LAST_TARGETS</big></li>
1276       <small> </small><small></small>
1277     </ol>
1278     <h4><big>
1279         clean</big></h4>
1280     <big>&nbsp;&nbsp;&nbsp;&nbsp; This causes all of the files in
1281       CLEANUPS to be
1282       removed and also executes all of the targets in OTHER_CLEANS.&nbsp; The
1283       language dependent system can override some of this behavior or it can
1284       just add more files to the list of CLEANUPS.
1285     </big>
1286     <h4><big>clean_subdirs</big></h4>
1287     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is similar to "make_subdirs" in
1288       that it
1289       descends
1290       into the subdirectories in no particular order, but it runs "make
1291       clean"
1292       in each of them.&nbsp; This allows a directory hierarchy of projects to
1293       be cleaned with one command.
1294     </big>
1295     <h4><big>finish</big></h4>
1296     <big>&nbsp;&nbsp;&nbsp;&nbsp; The "finish" target represents the
1297       completion
1298       of a make, whether successful or not.&nbsp; It reports the time and
1299       date
1300       (and logs them).
1301     </big>
1302     <h4><big>rm_links</big></h4>
1303     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target causes all link files in
1304       the
1305       current
1306       directory to be deleted.&nbsp; This is only applicable on a Unix
1307       operating
1308       system.
1309     </big>
1310     <h4><big>make_subdirs</big></h4>
1311     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target allows a makefile to
1312       specify that
1313       all of the subdirectories under the current directory should be scanned
1314       for makefiles and that those makefiles should be executed.&nbsp; If a
1315       makefile
1316       does not exist, it is skipped.&nbsp; Note that the subdirectories are
1317       descended
1318       into in no particular order; the order depends on how the operating
1319       system
1320       decides to list the directories.&nbsp; If the order of make is
1321       important,
1322       use BUILD_BEFORE instead.
1323     </big>
1324     <h4><big>start</big></h4>
1325     <big>&nbsp;&nbsp;&nbsp;&nbsp; The "start" target represents the
1326       beginning of
1327       the make.&nbsp; It reports the time and date (and logs them).
1328     </big>
1329     <h2><big><a name="LANG_INDEP_SCRIPTS"></a><u>Language Independent
1330           Files</u></big></h2>
1331     <h4><big>$(PARAMETER_FILE)</big></h4>
1332     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is a special
1333       file that has at least two purposes in .&nbsp; It is the source of
1334       the
1335       version number that will be stamped on all the appropriate DLLs and
1336       EXEs
1337       created during a build.&nbsp; It is also a place where build-wide
1338       compilation
1339       directives can be included so that they do not have to be passed on the
1340       command
1341       line.&nbsp; For C++ compilation, this is usually an INI file
1342       stored in the
1343       FEISTY_MEOW_DIR under the build folder.&nbsp;
1344       Here is a sample parameter file:
1345     </big>
1346     <blockquote><big><tt><font size="-1"><big>#\</big></font></tt> <br>
1347         <tt><font size="-1"><big>[version]</big></font></tt> <br>
1348         <tt><font size="-1"><big>major=14</big></font></tt> <br>
1349         <tt><font size="-1"><big>minor=3</big></font></tt> <br>
1350         <tt><font size="-1"><big>revision=140</big></font></tt> <br>
1351         <tt><font size="-1"><big>build=0</big></font></tt> </big><small> </small>
1352       <p><big><tt><font size="-1"><big>DEBUG=t</big></font></tt> <br>
1353           <tt><font size="-1"><big>OPTIMIZE=t</big></font></tt> <br>
1354         </big></p>
1355       <small> </small></blockquote>
1356     <big>Note the bizarre comment at the top of the makefile; this is
1357       used to
1358       hide
1359       the "[version]" section marker.&nbsp; The comment is required because
1360       the
1361       build parameter file is pulled directly into the makefile code to set
1362       the
1363       variables after the version stamp.&nbsp; Without a comment in front of
1364       the section, a syntax error would result.&nbsp; The "[version]" section
1365       marker is required because this file is also sometimes treated as a
1366       win32 INI file
1367       in order to read the version stamp.<br>
1368       &nbsp;&nbsp;&nbsp;&nbsp; The build version is stored in the first four
1369       entries.&nbsp; Our interpretation of the stamp is standard for "major"
1370       and "minor".&nbsp; We treat the "revision" as a build revision number;
1371       within a release, there will be numerous revisions--one for each new
1372       build
1373       that is performed.&nbsp; We then treat the "build" entry as a patch
1374       level
1375       within that particular build.&nbsp; When we perform our version
1376       checking,
1377       only the first three entries are compared; the patch level in "build"
1378       is
1379       considered irrelevant.
1380       <br>
1381       &nbsp;&nbsp;&nbsp;&nbsp; This example also specifies that the build
1382       should be a debug style (rather than release) build and that it should
1383       be optimizer.&nbsp; We can also see that
1384       the flags for bounds checker instrumentation and true time
1385       analysis support are commented out.<br>
1386     </big>
1387     <h4><big>badness_catcher.sh</big></h4>
1388     <big>&nbsp;&nbsp;&nbsp; &nbsp;Runs the command line passed
1389       in as a sub-shell and looks for error conditions. &nbsp;If an error
1390       occurred,
1391       the build is stopped and the CLAM_ERROR_SOUND is played.<br>
1392     </big>
1393     <h4><big>datestamp.sh</big></h4>
1394     <big>&nbsp;&nbsp;&nbsp; &nbsp;Echoes the time and date. &nbsp;This
1395       is a
1396       separate
1397       file to make the cross-platform difference less annoying.<br>
1398     </big>
1399     <h4><big>exit_make.sh</big></h4>
1400     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to stop dead in its
1401       tracks.
1402     </big>
1403     <h4><big>postconditions.sh</big></h4>
1404     <big>&nbsp;&nbsp;&nbsp; &nbsp;Invoked at the end of the
1405       language-invariant
1406       portion of a make.<br>
1407     </big>
1408     <h4><big>preconditions.sh</big></h4>
1409     <big>&nbsp;&nbsp;&nbsp; &nbsp;Invoked at the beginning of the
1410       language-invariant portion of a make.<br>
1411     </big>
1412     <h4><big>starter.sh</big></h4>
1413     <big>&nbsp;&nbsp;&nbsp;&nbsp; This shell script executes a command
1414       that is
1415       passed
1416       to it as its parameters and logs error conditions to standard
1417       output.&nbsp;
1418       It's used by the CATCHER macro.
1419     </big>
1420     <h2><small></small>
1421       <hr noshade="noshade" size="8" width="100%"></h2>
1422     <h2><big>
1423         <a name="CPP_VARS"></a><u>C++ Specific Variables</u></big></h2>
1424     <big>&nbsp;&nbsp;&nbsp;&nbsp; These variables are used throughout
1425       the C++
1426       compilation
1427       support.&nbsp; They are defined in "$/cpp/variables.def".
1428     </big>
1429     <h4><big>BASE_CPU</big></h4>
1430     <big>&nbsp;&nbsp;&nbsp;&nbsp; Allows specification of the
1431       processor that the
1432       build is targeted for.&nbsp; This is needed when special actions must
1433       be
1434       taken for different processor types.&nbsp; Valid values currently
1435       include
1436       m68k (for Motorola 68000 series), m68340 (specifically the 68340),
1437       x86 (intel 386 and upwards), and ppc860 (the PowerPC 860).
1438     </big>
1439     <h4><big>BUILD_LIST_FILE</big></h4>
1440     <big>&nbsp;&nbsp;&nbsp; &nbsp;The list of files that must
1441       be rebuilt. &nbsp;This is only used with compilers that support
1442       compilation
1443       of multiple source files with one invocation of the compiler (currently
1444       only
1445       MS-Visual C++).<br>
1446     </big>
1447     <h4><big>BUILD_WHACK_FILE</big></h4>
1448     <big>&nbsp;&nbsp;&nbsp; &nbsp;A list of object files that must be
1449       destroyed
1450       if
1451       the make fails. &nbsp;This is only relevant in the same situations as
1452       BUILD_LIST_FILE.<br>
1453     </big>
1454     <h4><big>COMPILER</big></h4>
1455     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable chooses the specific
1456       flags
1457       needed
1458       for the compiler.&nbsp; Not all operating system choices above are
1459       suitable
1460       with the COMPILER choices, but generally it is fairly obvious which are
1461       supported.&nbsp; The current possibilities include BORLAND_DOS,
1462       BORLAND_OS2,
1463       UNIX (default cc), GNU_OS2, GNU_LINUX, OBJECT_CENTER (Saber compiler),
1464       SUN_UNIX,
1465       VISUAL_CPP, and DIAB3.
1466     </big>
1467     <h4><big>COMPILER_FLAGS</big></h4>
1468     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the list of flags passed to
1469       the
1470       preprocessor
1471       and compiler. It is composed of the SYSTEM, the DEFINITIONS, the
1472       SEARCH_DIRS,
1473       and any user-included options. If flags that don't fit one of the
1474       categories
1475       are needed, they can be added here.
1476     </big>
1477     <h4><big>CONSOLE_MODE</big></h4>
1478     <big>&nbsp;&nbsp;&nbsp;&nbsp; This causes the program
1479       to be generated as a console application.&nbsp; This is relevant in
1480       systems
1481       (such as win32) where programs have a split personality depending on
1482       whether
1483       they are to have graphical user interfaces or just console interfaces.
1484     </big>
1485     <h4><big>DEBUG_FLAGS</big></h4>
1486     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are flags used for generating
1487       specialized
1488       versions of object files, such as ones that include debugging code
1489       (e.g.,
1490       for gdb) or ones that add code for profiling (e.g., gprof). Possible
1491       values
1492       in the Sun CenterLine Compiler environment are -g for debugging code
1493       and
1494       -pg for profiling.
1495     </big>
1496     <h4><big>DEFINITIONS</big></h4>
1497     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of compiler flags
1498       that define
1499       the
1500       value of C or C++ macros. These usually have the format of
1501       ?-D&lt;flag&gt;?,
1502       but in this particular variable only the &lt;flag&gt; itself should be
1503       listed
1504       (because the compiler option characters ?-D? are added automatically).
1505     </big>
1506     <h4><big>DEPENDENCY_ADDITIONS</big></h4>
1507     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of extra flags that
1508       gets passed
1509       to the auto-dependency tool.&nbsp; The list can vary for each compiler.
1510     </big>
1511     <h4><big>DEPS_FILE</big></h4>
1512     <big>&nbsp;&nbsp;&nbsp;&nbsp; This file is where the
1513       auto-dependency
1514       information
1515       is stored.&nbsp; The "makedep" program is used to generate
1516       auto-dependency
1517       information for the files listed in SOURCE.&nbsp; During a build, the
1518       DEPS_FILE
1519       is pulled into the actual code of the makefile; this causes the
1520       dependencies
1521       to be automatically included so that they can dictate the files that
1522       need
1523       to be rebuilt.
1524     </big>
1525     <h4><big>EXTRA_VERSIONS</big></h4>
1526     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of version files that
1527       also need
1528       to be updated to the main build version during a compilation.&nbsp;
1529       These
1530       are usually needed if a project compiles several executable files, and
1531       each one performs version checking.&nbsp; By default, any project
1532       containing
1533       a file called "version.ini" will get a version stamp from the main
1534       build
1535       version.
1536     </big>
1537     <h4><big>LIBRARIAN_FLAGS</big></h4>
1538     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of flags that are
1539       passed to the
1540       library creation tool.&nbsp; Sometimes this must be overridden for a
1541       particular
1542       compiler.
1543     </big>
1544     <h4><big>LIBS_USED</big></h4>
1545     <big>&nbsp;&nbsp;&nbsp;&nbsp; These are code libraries that the
1546       executables
1547       depend upon.&nbsp; They are searched for in any of the directories
1548       listed
1549       in the LIBRARY_SEARCH_PATH.
1550     </big>
1551     <h4><big>LOAD_FLAG_PREFIX &amp; LOAD_FLAG_SUFFIX</big></h4>
1552     <big>&nbsp;&nbsp;&nbsp;&nbsp; These tell the linker and loader how
1553       to deal
1554       with
1555       the files and where to locate library components. The prefix is listed
1556       on the compilation command line before the object files are listed, and
1557       the suffix after. The prefix should contain information such as the
1558       directories
1559       to be searched for code libraries (although they should be added to
1560       LIBRARY_SEARCH_PATH).&nbsp;
1561       In the suffix definition, actual library loading statements (like
1562       -lmath)
1563       can be included (although they should be listed in a different form in
1564       LIBS_USED or LOCAL_LIBS_USED).
1565     </big>
1566     <h4><big>LOCAL_LIBS_USED</big></h4>
1567     <big>&nbsp;&nbsp;&nbsp;&nbsp; The names in this list actually
1568       cause the
1569       OBJECTS
1570       to be recompiled when the libraries listed have changed.&nbsp; To
1571       accomplish
1572       this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather
1573       than
1574       at some arbitrary place on the LIBRARY_SEARCH_PATH.&nbsp; These
1575       libraries
1576       also must follow the special naming convention followed by ; if
1577       "basis"
1578       is an entry in this list, then a library called "basis.lib" will be
1579       sought
1580       during the build.
1581     </big>
1582     <h4><big>NO_COMPILE</big></h4>
1583     <big>&nbsp;&nbsp;&nbsp; &nbsp;Specifies that no compilation
1584       should be performed. &nbsp;Nothing in the SOURCE or TARGETS macros will
1585       be
1586       built.<br>
1587     </big>
1588     <h4><big>NO_DEPS</big></h4>
1589     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is an exclusion flag.&nbsp; If
1590       it is
1591       defined,
1592       then no auto-dependency files will be generated.&nbsp; This is useful
1593       if
1594       you're missing the makedep tool and trying to compile it.<br>
1595     </big>
1596     <h4><big>OBJECTS</big></h4>
1597     <big>&nbsp;&nbsp;&nbsp;&nbsp; The OBJECTS are all those files that
1598       need to
1599       be
1600       created during compilation.&nbsp; Usually this list is filled based on
1601       the files in SOURCE.
1602     </big>
1603     <h4><big>OPTIMIZE</big></h4>
1604     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create optimized
1605       code.&nbsp;
1606       The default optimization is for speed.
1607     </big>
1608     <h4><big>REBUILD</big></h4>
1609     <big>&nbsp;&nbsp;&nbsp;&nbsp; If the REBUILD variable is
1610       non-empty, then all
1611       files listed in the SOURCE variable are touched.&nbsp; This should
1612       cause
1613       all of those files to be rebuilt during the compilation.&nbsp;
1614       Occasionally
1615       GNU make will complain that a file is newer than the current time, but
1616       this does not usually cause any problems.
1617     </big>
1618     <h4><big>SOURCE</big></h4>
1619     <big>&nbsp;&nbsp;&nbsp;&nbsp; The SOURCE variable is a list of
1620       files that
1621       are
1622       to be compiled in order to create the final products of the
1623       project.&nbsp;
1624       These can be C++ source files (*.cpp), Win32 resource files (*.rc)
1625       and
1626       other types of source files.&nbsp; The list of objects to create will
1627       be
1628       determined by transforming the list of SOURCE files (such as by turning
1629       a file called "fud.cpp" into an object called "fud.obj").&nbsp; More
1630       file
1631       types will be added as they are needed.
1632     </big>
1633     <h4><big>STATIC</big></h4>
1634     <big>&nbsp;&nbsp;&nbsp;&nbsp; Causes the make to create statically
1635       linked
1636       targets.&nbsp;
1637       Executables or dynamic libraries will not link in any compiler supplied
1638       dynamic libraries, nor will they require them during run-time.
1639     </big>
1640     <h4><big>TYPE</big></h4>
1641     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a variable that describes
1642       the kind of
1643       project that is being compiled.&nbsp; Knowing the type of project is
1644       necessary
1645       because it controls some elements of the compilation and also of the
1646       final
1647       promotion of the compiled products.&nbsp; There are three TYPEs
1648       supported
1649       so far:
1650     </big>
1651     <ul>
1652       <small> </small><big> </big><small> </small>
1653       <li><big>library: indicates that the project will be primarily
1654           creating
1655           static
1656           or
1657           dynamic libraries.</big></li>
1658       <small> </small><big> </big><small> </small>
1659       <li><big>application: indicates that the project will create
1660           executables.</big></li>
1661       <small> </small><big> </big><small> </small>
1662       <li><big>test: indicates that the project constructs test
1663           programs.</big></li>
1664       <small> </small><small></small>
1665     </ul>
1666     <big>Projects of the "library" type will follow the special&nbsp;
1667       rules for
1668       their include directory (which is created as a copy of headers in the
1669       library
1670       directory).&nbsp; Library projects will also have their final products
1671       copied to the lib or dll subdirectories of the build directory being
1672       created.&nbsp;
1673       Projects that are "application"s will have their executables copied to
1674       the executable directory in the build.&nbsp; And "test" projects will
1675       be
1676       promoted to a subdirectory named after the PROJECT that resides under
1677       the
1678       test hierarchy in the build.
1679     </big>
1680     <h2><big><a name="DIRECTORY_VARS"></a><u>C++ Directory Structure
1681           Variables</u></big></h2>
1682     <h4><big>BASE_OUTPUT_PATH</big></h4>
1683     <big>&nbsp;&nbsp;&nbsp; &nbsp;This is the parent directory
1684       for object files generated for the specified type of CPU and the style
1685       of
1686       build (e.g. debug or release builds).<br>
1687     </big>
1688     <h4><big>CPU_BUILD_DIR</big></h4>
1689     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable can be used to
1690       distinguish
1691       directory
1692       names used for output.&nbsp; It includes the cpu name and the type of
1693       build.
1694     </big>
1695     <h4><big>DYNAMIC_LIBRARY_DIR</big></h4>
1696     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where dynamic
1697       libraries will be
1698       stored after creation.<br>
1699     </big>
1700     <h4><big>EXECUTABLE_DIR</big></h4>
1701     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where executable files
1702       will be
1703       stored after creation.<br>
1704     </big>
1705     <h4><big>FINAL_DIR</big></h4>
1706     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the directory
1707       where the
1708       finished
1709       compilation products are stored, currently only import libraries for
1710       dynamic libraries.&nbsp;
1711       It is usually a directory under the OUTPUT_PATH named "final".
1712     </big>
1713     <h4><big>HEADER_SEARCH_PATH</big></h4>
1714     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1715       will be
1716       searched
1717       for C++ header files (files ending in ?.h?).
1718     </big>
1719     <h4><big>HOOPLE_HEADERS</big></h4>
1720     <big>&nbsp;&nbsp;&nbsp;&nbsp; The two standard places to look for
1721       headers
1722       (the repository and the third party directory) are listed in this
1723       variable.
1724     </big>
1725     <h4><big>HOOPLE_LIBRARIES</big></h4>
1726     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where our libraries are
1727       located.&nbsp; It is usually a subdirectory called "lib" under the
1728       repository
1729       directory.
1730     </big>
1731     <h4><big>LIBRARY_SEARCH_PATH</big></h4>
1732     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1733       will be
1734       searched
1735       for C++ library archives (files ending in ".a" or ".lib").
1736     </big>
1737     <h4><big>LOCAL_HEADERS</big></h4>
1738     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable provides a way to
1739       include
1740       headers
1741       prior to the default locations in the search path.&nbsp; For example,
1742       if
1743       you are compiling locally and have some headers that are not present in
1744       the build you are using, then you can specify where they are in this
1745       variable.
1746     </big>
1747     <h4><big>LOCAL_LIBRARIES</big></h4>
1748     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable allows other library
1749       directories
1750       to be added prior to the default search locations.&nbsp; This enables
1751       substitute
1752       static or import libraries to be used instead of the standard ones
1753       present
1754       in the build.
1755     </big>
1756     <h4><big>STATIC_LIBRARY_DIR</big></h4>
1757     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the location where code
1758       libraries are
1759       to be copied during promotion and where they are to be searched for
1760       when
1761       listed in LOCAL_LIBS_USED.&nbsp; Under Unix, these libraries have a
1762       ?.a?
1763       suffix and are created with the "ar" program.&nbsp; Under Win32,
1764       these
1765       libraries have a ?.lib? suffix and are created with "link".
1766     </big>
1767     <h4><big>OBJECT_DIR</big></h4>
1768     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where object files will be
1769       stored
1770       during
1771       compilation for the target type being produced.
1772     </big>
1773     <h4><big>OUTPUT_DIRECTORY_LIST</big></h4>
1774     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1775       need to be
1776       created under the OUTPUT_PATH.&nbsp; It contains the "final" directory
1777       where all finished products are stored, as well as all the intermediate
1778       directories for objects.
1779     </big>
1780     <h4><big>OUTPUT_PATH</big></h4>
1781     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the temporary file storage
1782       area.&nbsp;
1783       Any files that are created during the compilation process will be
1784       stored
1785       under here in a subdirectory named after the PROJECT.
1786     </big>
1787     <h4><big>OUTPUT_ROOT</big></h4>
1788     <big>&nbsp;&nbsp;&nbsp;&nbsp; This specifies the root portion of
1789       the
1790       OUTPUT_PATH.&nbsp;
1791       It lets a PC build use drive letters for the root, while a Unix build
1792       can
1793       specify a directory hierarchy.
1794     </big>
1795     <h4><big>SEARCH_DIRS</big></h4>
1796     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is a list of directories that
1797       will be
1798       searched
1799       for both C++ header files and for C++ code libraries.&nbsp; The items
1800       placed
1801       on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the
1802       HEADER_SEARCH_PATH.&nbsp;
1803       The reasoning behind this variable is lost in antiquity.
1804     </big>
1805     <h4><big>TESTS_DIR <br>
1806       </big></h4>
1807     <big>&nbsp;&nbsp;&nbsp; &nbsp;The directory where test programs
1808       will be
1809       stored after creation.<br>
1810     </big>
1811     <h4><big>THIRD_PARTY_DIR</big></h4>
1812     <big>&nbsp;&nbsp;&nbsp;&nbsp; Third party components are sometimes
1813       used in
1814       the
1815       creation of products.&nbsp; The directory is expected to have a
1816       structure
1817       containing "include" and "lib" subdirectories where headers and
1818       libraries
1819       are stored.
1820     </big>
1821     <h2><big><a name="CPP_FLAGS"></a><u>Compiler Dependent Flags</u></big></h2>
1822     <h4><big>
1823         CC</big></h4>
1824     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the C++ compiler
1825       executable.
1826     </big>
1827     <h4><big>COMPILER_HEADER_DIR</big></h4>
1828     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the compiler's header
1829       (or
1830       include)
1831       root directory is located.&nbsp; It is usually based on the root
1832       directory.
1833     </big>
1834     <h4><big>COMPILER_LIBRARY_DIR</big></h4>
1835     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is where the code libraries for
1836       the
1837       compiler
1838       are located.&nbsp; It is usually based on the root directory.
1839     </big>
1840     <h4><big>COMPILER_ROOT_DIR</big></h4>
1841     <big>&nbsp;&nbsp;&nbsp;&nbsp; This should automatically be set to
1842       the
1843       appropriate
1844       local directory where the C++ compiler is located.
1845     </big>
1846     <h4><big>CREATE_LIBRARY_FLAG</big></h4>
1847     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag, if required, specifies
1848       the text
1849       that
1850       must precede the name of a library to create.&nbsp; It is passed to the
1851       library creation tool.
1852     </big>
1853     <h4><big>DEF_FILE</big></h4>
1854     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Win32
1855       programs.&nbsp;
1856       It specifies the name of a DEF file for all of the products created in
1857       the project.
1858     </big>
1859     <h4><big>LIB_PREFIX &amp; LIB_SUFFIX</big></h4>
1860     <big>&nbsp;&nbsp;&nbsp; &nbsp;The portions of a library's name
1861       dictated by the operating system. &nbsp;For example, on Unix the prefix
1862       is "lib"
1863       and the suffix is ".a", leading to library names like "libbasis.a" for
1864       the
1865       basis library. &nbsp;On win32, the prefix is "" and the suffix is
1866       ".lib", leading
1867       to library names like "basis.lib".<br>
1868     </big>
1869     <h4><big>LIBRARY_NAME_FLAG</big></h4>
1870     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag contains the text that
1871       specifies a
1872       library
1873       that will be included in a link.&nbsp; It is often "-l".
1874     </big>
1875     <h4><big>LIBRARY_PATH_FLAG</big></h4>
1876     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag provides the text needed
1877       to add
1878       another
1879       library search path.&nbsp; Multiple occurrences of this flag followed
1880       by
1881       a directory name are allowed by most compilers.
1882     </big>
1883     <h4><big>LIBRARY_TOOL</big></h4>
1884     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program
1885       responsible
1886       for
1887       creating libraries.
1888     </big>
1889     <h4><big>LINK_TOOL</big></h4>
1890     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is the name of the program that
1891       links.&nbsp;
1892       This is sometimes the same as the compiler (CC) and sometimes the same
1893       as the librarian (LIBRARY_TOOL).
1894     </big>
1895     <h4><big>LINKER_OPTION_SEPARATOR</big></h4>
1896     <big>&nbsp;&nbsp;&nbsp;&nbsp; In some compilers, linker options
1897       need to be
1898       separated
1899       from compiler options that occur on the same command line.&nbsp; This
1900       flag
1901       serves that purpose.
1902     </big>
1903     <h4><big>LINKER_OUTPUT_FLAG</big></h4>
1904     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is sometimes required by a
1905       linker
1906       for
1907       specifying the name of the library or executable that it is creating.
1908     </big>
1909     <h4><big>OBJECT_NAME_FLAG</big></h4>
1910     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag is used to specify the
1911       name of an
1912       object
1913       file being created.&nbsp; It is passed to the compiler to override
1914       whatever
1915       default name would be used.
1916     </big>
1917     <h2><big><u><a name="vcpp_only"></a>Microsoft-Visual C++ Only</u><br>
1918       </big></h2>
1919     <h4><big>USE_MFC</big></h4>
1920     <big>&nbsp;&nbsp;&nbsp;&nbsp; This flag only applies to Visual C++
1921       and
1922       indicates
1923       that MFC is to be used in creating this project.&nbsp; This is usually
1924       the case for GUI applications.
1925     </big>
1926     <h4><big>VC_ROOT</big></h4>
1927     <big>&nbsp;&nbsp;&nbsp;&nbsp; This is an override that allows the
1928       compiler
1929       root
1930       directory to be customized without changing the&nbsp; code.&nbsp; If
1931       VC_ROOT
1932       is set (either in a makefile or as an external variable), then it will
1933       be used in place of the COMPILER_ROOT_DIR.&nbsp; The best way to use
1934       this
1935       override is as an external environment variable; this allows makefiles
1936       to remain the same despite your local configuration of the compiler.
1937       <br>
1938       &nbsp;&nbsp;&nbsp;&nbsp; Note that this variable should use
1939       forward-slashes,
1940       where DOS/Win32 would use backslashes.&nbsp; Also, if you have
1941       installed
1942       Visual C++ in a directory path containing space characters, then please
1943       use the 8.3 notation for the directories containing the spaces; this
1944       allows
1945       the name to be passed around successfully.&nbsp; For example...
1946     </big>
1947     <center><small></small><big> </big><big> </big><big> </big><big> </big><big></big><big></big><big>
1948       </big><big> </big><big> </big><big> </big><big>
1949       </big><big> </big><big> </big><big> </big><small> </small><small></small><small>
1950       </small><small> </small><small> </small><small> </small><small>
1951       </small><small> </small><small> </small><small> </small><small> </small><small></small><small>
1952       </small><small> </small><small> </small><small> </small>
1953       <table cellpadding="8" cellspacing="4">
1954         <tbody>
1955           <tr>
1956             <td><big> </big><small> </small>
1957               <center><big><u>If Visual C++ Is Installed In</u></big></center>
1958               <small> </small><big> </big></td>
1959             <td><big> </big><small> </small>
1960               <center><big><u>Then VC_ROOT Should Be</u></big></center>
1961               <small> </small><big> </big></td>
1962           </tr>
1963           <tr>
1964             <td><big> </big><small> </small>
1965               <center><big>c:\devstudio\vc</big></center>
1966               <small> </small><big> </big></td>
1967             <td><big> </big><small> </small>
1968               <center><big>c:/devstudio/vc</big></center>
1969               <small> </small><big> </big></td>
1970           </tr>
1971           <tr>
1972             <td><big> </big><small> </small>
1973               <center><big>c:\program files\devstudio\vc</big></center>
1974               <small> </small><big> </big></td>
1975             <td><big> </big><small> </small>
1976               <center><big>c:/progra~1/devstudio/vc</big></center>
1977               <small> </small><big> </big></td>
1978           </tr>
1979         </tbody>
1980       </table>
1981       <small></small></center>
1982     <h4><big>VCS_ROOT</big></h4>
1983     <big>&nbsp;&nbsp;&nbsp;&nbsp; Similarly to the VC_ROOT, this
1984       variable points
1985       at the root of the C# support for Visual Studio.Net.<br>
1986     </big>
1987     <h4><big>FRAMEWORK_DIR</big></h4>
1988     <big>&nbsp;&nbsp;&nbsp;&nbsp; This variable specifies the location
1989       of the
1990       .Net framework directory.&nbsp; On MS-Windows XP, the default should be
1991       fine.&nbsp; For MS-Windows 2000 or other Win32 OSes, the windows
1992       directory
1993       should be "winnt" instead.&nbsp; If the operating system is configured
1994       in a non-default way, the framework directory can be specified in an
1995       environment variable.<br>
1996     </big>
1997     <h4><big>VCPP_USE_BASE</big></h4>
1998     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that standard Win32
1999       libraries should
2000       be linked in.<br>
2001     </big>
2002     <h4><big>VCPP_USE_GUI</big></h4>
2003     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MFC libraries
2004       should be
2005       linked in.
2006     </big>
2007     <h4><big>VCPP_USE_OLE</big></h4>
2008     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the COM / OLE
2009       libraries should
2010       be linked in.
2011     </big>
2012     <h4><big>VCPP_USE_RPC</big></h4>
2013     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-RPC libraries
2014       should be
2015       linked in.<br>
2016     </big>
2017     <h4><big>VCPP_USE_SOCK</big></h4>
2018     <big>&nbsp;&nbsp;&nbsp;&nbsp; Specifies that the MS-WinSock
2019       libraries should
2020       be linked in.<br>
2021     </big>
2022     <h2><big><a name="CPP_RULES"></a><u>C++ Specific Rules</u></big></h2>
2023     <big>&nbsp;&nbsp;&nbsp;&nbsp; These types of targets have one
2024       thing in
2025       common;
2026       if any of the items that a target depends on in SOURCE or
2027       LOCAL_LIBS_USED
2028       or included files or whatever have changed since the last time the
2029       target
2030       was created, then it is recompiled.
2031     </big>
2032     <h4><big>%.bad</big></h4>
2033     <big>&nbsp;&nbsp;&nbsp; &nbsp;Causes the make to die. &nbsp;This
2034       is added when an incorrect file type is spotted in a list of targets.<br>
2035     </big>
2036     <h4><big>%.dll</big></h4>
2037     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create dynamically linked
2038       libraries from
2039       the SOURCE.
2040     </big>
2041     <h4><big>%.elf</big></h4>
2042     <big>&nbsp;&nbsp;&nbsp; &nbsp;Creates elf-formatted binaries for
2043       use with a
2044       firmware build (a specialized RTOS is the only one currently supported).<br>
2045     </big>
2046     <h4><big>%.exe</big></h4>
2047     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates an executable program
2048       using all
2049       of
2050       the objects and libraries specified.&nbsp; It is therefore important in
2051       a&nbsp; makefile to only have executables that depend on the same group
2052       of object files.&nbsp; The hidden agenda in the "exe" type of target is
2053       that a file ending in ".cpp" must exist; this is taken as the root of
2054       the
2055       executable.&nbsp; It should usually contain the main() function (or its
2056       equivalent).
2057     </big>
2058     <h4><big>%.lib</big></h4>
2059     <big>&nbsp;&nbsp;&nbsp;&nbsp; This creates static libraries from
2060       the files
2061       listed
2062       in OBJECTS.
2063     </big>
2064     <h4><big>%.nil</big></h4>
2065     <big>&nbsp;&nbsp;&nbsp; &nbsp;A blank target for test compiles.<br>
2066     </big>
2067     <h4><big>%.obj</big></h4>
2068     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create object files from C++
2069       source
2070       files
2071       (files ending in .c or .cpp).
2072     </big>
2073     <h4><big>%.res</big></h4>
2074     <big>&nbsp;&nbsp;&nbsp;&nbsp; These create compiled resource files
2075       from RC
2076       files
2077       in the SOURCE list.
2078     </big>
2079     <h2><big><a name="CPP_TARGETS"></a><u>C++ Specific Targets</u></big></h2>
2080     <h4><big>
2081         check_requirements</big></h4>
2082     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target ensures that certain
2083       characteristics
2084       of the makefile are present.&nbsp; It complains and aborts the make if
2085       they are missing.
2086     </big>
2087     <h4><big>post_compilation</big></h4>
2088     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target finalizes the
2089       compilation by
2090       running
2091       the postconditions script.&nbsp; If PROMOTE is true, then the final
2092       products
2093       are copied into the repository.
2094     </big>
2095     <h4><big>pre_compilation</big></h4>
2096     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target executes the
2097       preconditions script
2098       to set up the compilation's output directories.
2099     </big>
2100     <h4><big>rebuild</big></h4>
2101     <big>&nbsp;&nbsp;&nbsp;&nbsp; This target performs the actions of
2102       rebuilding.&nbsp;
2103       This mainly involves touching all of the files in SOURCE before the
2104       compilation
2105       has really started.
2106     </big>
2107     <h2><big><a name="CPP_SCRIPTS"></a><u>C++ Specific Files</u></big></h2>
2108     <h4><big>postconditions.sh</big></h4>
2109     <big>&nbsp;&nbsp;&nbsp;&nbsp; After a compilation has succeeded,
2110       the
2111       postconditions
2112       script performs the final actions required.&nbsp; The nature of these
2113       actions
2114       depends on the type of project being made.&nbsp; For a library project,
2115       the script copies the headers to the project's include directory and
2116       copies
2117       libraries to the appropriate locations.&nbsp; For application and test
2118       program targets, the script copies the final products to the
2119       appropriate
2120       repository directory.
2121     </big>
2122     <h4><big>preconditions.sh</big></h4>
2123     <big>&nbsp;&nbsp;&nbsp;&nbsp; Before any targets are compiled, the
2124       preconditions
2125       script ensures that the appropriate output directories exist for the
2126       project.&nbsp;
2127       The script also calls the version utilities to update the project's
2128       version
2129       file and to create any required resource files.<br>
2130     </big>
2131     <h4><big>rebuild_oldies.sh</big></h4>
2132     <big>&nbsp;&nbsp;&nbsp; &nbsp;Used for compilers that support
2133       multiple code
2134       files
2135       in one invocation. &nbsp;This is launched to compile a batch of sources
2136       and
2137       catch any errors.<br>
2138     </big>
2139     <hr noshade="noshade" size="8" width="100%">
2140     <center><small></small>
2141       <h2><big><a name="EXAMPLES"></a>CLAM Example Makefiles</big></h2>
2142       <small></small></center>
2143     <big>&nbsp;&nbsp;&nbsp;&nbsp; These examples show some common
2144       patterns for
2145       how&nbsp; is used.&nbsp; The makefiles below are actually used in real
2146       software
2147       projects.
2148     </big>
2149     <h3><big>Library-Only Makefile</big></h3>
2150     <big>This example creates a dynamic library.
2151     </big>
2152     <ul>
2153       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2154       </small>
2155       <p><big><tt>PROJECT = mechanisms</tt><br>
2156           <tt>TYPE = library</tt> <br>
2157           <tt>SOURCE = delayer.cpp eventmgr.cpp event_po.cpp heartbea.cpp
2158             instance.cpp
2159             \</tt> <br>
2160           <tt>&nbsp; libmain.cpp monitor.cpp semaphor.cpp state_ma.cpp
2161             timer.cpp
2162             time_sta.cpp</tt> <br>
2163           <tt>TARGETS = mechanisms.dll</tt> <br>
2164           <tt>LOCAL_LIBS_USED = basis</tt> <br>
2165           <tt>DEFINITIONS += BUILD_MECHANISMS USE_HOOPLE_DLLS</tt> </big></p>
2166       <small> </small><big> </big><small> </small>
2167       <p><big><tt>include cpp/rules.def</tt></big></p>
2168       <small> </small><small></small>
2169     </ul>
2170     <big>The dynamic library created here is mechanisms.dll.&nbsp; The
2171       basis
2172       library is linked
2173       in also.&nbsp; The file "roller.cpp" will also be copied to the build
2174       directory's
2175       include path, presumably since it is a template code file.
2176     </big>
2177     <h3><big>Library Plus Executable Makefile</big></h3>
2178     <big>This example shows the basis makefile with a couple of test
2179       programs
2180       also
2181       being generated.
2182     </big>
2183     <ul>
2184       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2185       </small>
2186       <p><big><tt>PROJECT = basis</tt> <br>
2187           <tt>TYPE = library</tt> <br>
2188           <tt>SOURCE = chaos.cpp checkup.cpp guards.cpp \</tt> <br>
2189           <tt>&nbsp; istring.cpp itime.cpp logger.cpp matrix.cpp
2190             portable.cpp \</tt> <br>
2191           <tt>&nbsp; realtime.cpp textdump.cpp timezone.cpp utility.cpp \</tt> <br>
2192           <tt>&nbsp; version_checker.cpp version_record.cpp</tt> <br>
2193           <tt>TARGETS = basis.lib t_string.exe t_alloc.exe</tt> </big></p>
2194       <small> </small><big> </big><small> </small>
2195       <p><big><tt>include cpp/rules.def</tt></big></p>
2196       <small> </small><small></small>
2197     </ul>
2198     <big>Note that the executables
2199       "t_string.exe" and "t_alloc.exe" require files called "t_string.cpp"
2200       and
2201       "t_alloc.cpp" to exist.&nbsp; These files are expected to contain the
2202       "main()"
2203       or "WinMain()" functions (or the MFC application object).&nbsp; All of
2204       the
2205       files in the SOURCE variable will be included in each final executable.
2206     </big>
2207     <h3><big>Executable-Only Makefile</big></h3>
2208     <big>This example is produces several test programs that exercise
2209       the
2210       associated
2211       library.
2212     </big>
2213     <ul>
2214       <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2215       </small>
2216       <p><big><tt>PROJECT = t_basis</tt> <br>
2217           <tt>TYPE = test</tt> <br>
2218           <tt>SOURCE = instance.cpp t_basis.rc</tt> <br>
2219           <tt>TARGETS = t_alloc.exe t_chaos.exe t_checku.exe t_dattim.exe \</tt>
2220           <br>
2221           <tt>&nbsp; t_matrix.exe t_sequen.exe t_sorts.exe t_string.exe \</tt> <br>
2222           <tt>&nbsp; t_texdmp.exe</tt> <br>
2223           <tt>LOCAL_LIBS_USED = basis</tt> </big></p>
2224       <small> </small><big> </big><small> </small>
2225       <p><big><tt>include cpp/rules.def</tt></big></p>
2226       <small> </small><small></small>
2227     </ul>
2228     <big>The programs "t_alloc.exe" and so on will require C++ files
2229       with the
2230       same
2231       prefix (t_alloc.cpp) to contain the main program (as in the previous
2232       example).&nbsp;
2233       The items in the SOURCE list will be included in each executable, and
2234       the
2235       basis library will be linked in.
2236     </big>
2237     <h2><big><a name="CLAM_HINTS"></a>CLAM Hints</big></h2>
2238     <big>&nbsp;&nbsp;&nbsp;&nbsp; This section
2239       is devoted to untangling snags that have been encountered in the
2240       past.&nbsp;
2241       Hopefully problems you encounter will be discussed here. &nbsp;Please
2242       contribute
2243       any new problems found to the <a href="#lib_manager">library
2244         administrator</a>.
2245     </big>
2246     <h3><big>Problem:</big></h3>
2247     <big>&nbsp;&nbsp;&nbsp;&nbsp; A message like:
2248     </big>
2249     <ul>
2250       <small> </small><big> </big><small> </small>
2251       <ul>
2252         <small> </small><big>make: *** No rule to make target
2253           `o:/x86_w32_rel/project/final/myproj.dll',
2254           needed by `all'.&nbsp; Stop. </big><small> </small>
2255       </ul>
2256       <small> </small><small></small>
2257     </ul>
2258     <big>is displayed during a make.
2259     </big>
2260     <h3><big>Solution:</big></h3>
2261     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent reason for
2262       receiving a
2263       message
2264       similar to the above is that there is a file listed in SOURCE that
2265       either
2266       does not exist or that is capitalized differently from how it is
2267       listed.&nbsp;
2268       Check that all the files in SOURCE are in the makefile's directory and
2269       that the exact spelling of those files (including their case) is
2270       correct.
2271       <br>
2272       &nbsp;&nbsp;&nbsp;&nbsp; Another potential cause of this problem is
2273       if a file is included in the SOURCE that&nbsp; does not
2274       recognize.&nbsp;
2275       The standard compilable files are supported (*.cpp, *.c, *.rc), but it
2276       is possible that a makefile must handle a non-standard extension (such
2277       as *.idl).&nbsp; Either the user's makefile must supply a rule for
2278       processing
2279       this type of file or the user must negotiate with the&nbsp;
2280       administrator
2281       to get that type of target added to the&nbsp; support.
2282     </big>
2283     <h3><big>Problem:</big></h3>
2284     <big>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Clam is complaining about programs
2285       not being
2286       found
2287       during a build.
2288     </big>
2289     <h3><big>Solution:</big></h3>
2290     <big>&nbsp;&nbsp;&nbsp;&nbsp; The most frequent cause of this
2291       problem is a
2292       directory
2293       not being on your path.&nbsp; The compilation tools bin (~/hoople/bin)
2294       directory must be in
2295       the PATH variable.
2296       <br>
2297       &nbsp;&nbsp;&nbsp;&nbsp; Problems are occasionally seen when the PATH
2298       contains directory names that have spaces in them.&nbsp; Try using the
2299       shorter 8.3 form of the directory name.
2300       <br>
2301       &nbsp;&nbsp;&nbsp;&nbsp; An even more obscure situation sometimes
2302       occurs: paths with networked drives seem to somehow hide paths with
2303       local drives that
2304       are listed later in the PATH variable.&nbsp; The cause of this is
2305       unknown,
2306       although it was thought to be caused by NetWare at one point.&nbsp; To
2307       fix
2308       the situation, move the local paths before the networked ones.<br>
2309       <br>
2310     </big>
2311     <hr noshade="noshade" size="8" width="100%">
2312     <center><small></small>
2313       <h2><big><a name="ACKS"></a>Acknowledgements</big></h2>
2314       <small></small></center>
2315     <center><big>Thanks to April Bly Monnen for the wonderful cover
2316         art.
2317       </big><small></small>
2318       <p><big>Thanks to Kevin Wika for some early help with makefiles.
2319         </big></p>
2320       <small></small><big><big>
2321         </big></big><small></small>
2322       <hr noshade="noshade" size="8" width="100%"></center>
2323     <big><br>
2324       <br>
2325     </big>
2326   </body>
2327 </html>