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