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