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