1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
4 <meta content="text/html; charset=iso-8859-1" http-equiv="content-type">
5 <meta content="Fred T. Hamster" name="Author">
6 <meta name="generator" content="Mozilla/5.0 (X11; U; Linux i686; en-US) [Mozilla]">
7 <title>CLAM Reference Manual</title>
9 <body link="#33ff33" text="#ffff99" vlink="#009900" bgcolor="#400080" alink="#ff9900">
12 <h1><big>CLAM: Coordinated Librarian &</big></h1>
13 <h1><big>Automatic Maker</big></h1>
14 <small></small></center>
15 <center><big><img src="../../infobase/pictures/clams_tran.gif" height="347" width="392"></big></center>
18 <h2><big>Tutorial and Reference Manual</big></h2>
19 <small></small></center>
22 <address><big><a name="lib_manager"></a>By Chris Koeritz (<a href="mailto:koeritz@gruntose.com">koeritz@gruntose.com</a>)</big></address>
23 <small></small></center>
27 <hr noshade="noshade" size="8" width="100%"></h2>
28 <small></small></center>
31 <h2><big>Table of Contents</big></h2>
32 <small></small></center>
34 <small> </small><big> </big><small> </small>
35 <li><big> <a href="#EXECUTIVE_SUMMARY">Executive Summary</a></big></li>
36 <small> </small><big> </big><small> </small>
37 <li><big> <a href="#PREPARATION">Preparing Your Computer to Use
39 <small> </small><big> </big><small> </small>
41 <small> </small><big> </big><small> </small>
42 <li><big> <a href="#STEPS_NEEDED">Necessary Steps</a></big></li>
43 <small> </small><big> </big><small> </small>
45 <small> </small><big> </big><small> </small>
46 <li><big> <a href="#TUTORIAL">CLAM Tutorial</a></big></li>
47 <small> </small><big> </big><small> </small>
49 <small> </small><big> </big><small> </small>
50 <li><big> <a href="#CAVEATS">Caveats</a></big></li>
51 <small> </small><big> </big><small> </small>
52 <li><big> <a href="#TUT_BASICS">Basics</a></big></li>
53 <small> </small><big> </big><small> </small>
54 <li><big> <a href="#TUT_COMMON">Common Files</a></big></li>
55 <small> </small><big> </big><small> </small>
56 <li><big> <a href="#TUT_IMPORTANT_VARS">Important Variables</a></big></li>
57 <small> </small><big> </big><small> </small>
58 <li><big> <a href="#TUT_VAR_ASSIGN">Variable Assignment</a></big></li>
59 <small> </small><big> </big><small> </small>
60 <li><big> <a href="#TUT_OPTIONAL_VARS">Optional Variables</a></big></li>
61 <small> </small><big> </big><small> </small>
62 <li><big> <a href="#WRITING_RULES">Writing Your Own Rules</a></big></li>
63 <small> </small><big> </big><small> </small>
64 <li><big> <a href="#TUT_CONCLUSION">Conclusion</a></big></li>
65 <small> </small><big> </big><small> </small>
67 <small> </small><big> </big><small> </small>
68 <li><big> <a href="#REFERENCE">CLAM Reference</a></big></li>
69 <small> </small><big> </big><small> </small>
71 <small> </small><big> </big><small> </small>
72 <li><big> <a href="#LANG_INDEP_VARS">Language Independent
73 Variables</a></big></li>
74 <small> </small><big> </big><small> </small>
75 <li><big> <a href="#LANG_INDEP_RULES">Language Independent
77 <small> </small><big> </big><small> </small>
78 <li><big> <a href="#LANG_INDEP_TARGETS">Language Independent
79 Targets</a></big></li>
80 <small> </small><big> </big><small> </small>
81 <li><big> <a href="#LANG_INDEP_SCRIPTS">Language Independent
83 <small> </small><big> </big><small> </small>
84 <li><big> <a href="#CPP_VARS">C++ Specific Variables</a></big></li>
85 <small> </small><big> </big><small> </small>
87 <small> </small><big> </big><small> </small>
88 <li><big> <a href="#DIRECTORY_VARS">Directory Structure
89 Variables</a></big></li>
90 <small> </small><big> </big><small> </small>
91 <li><big> <a href="#CPP_FLAGS">Compiler Dependent Flags</a></big></li>
92 <small> </small><big> </big><small> </small>
93 <li><big><a href="#vcpp_only">Microsoft Visual C++ Only</a><br>
95 <small> </small><big> </big><small> </small>
96 <li><big> <a href="#SUPPORT_EXTENSIONS">Support for
98 Extensions</a></big></li>
99 <small> </small><big> </big><small> </small>
101 <small> </small><big> </big><small> </small>
102 <li><big> <a href="#CPP_RULES">C++ Specific Rules</a></big></li>
103 <small> </small><big> </big><small> </small>
104 <li><big> <a href="#CPP_TARGETS">C++ Specific Targets</a></big></li>
105 <small> </small><big> </big><small> </small>
106 <li><big> <a href="#CPP_SCRIPTS">C++ Specific Files</a></big></li>
107 <small> </small><big> </big><small> </small>
109 <small> </small><big> </big><small> </small>
110 <li><big> <a href="#EXAMPLES">Example CLAM Makefiles</a></big></li>
111 <small> </small><big> </big><small> </small>
112 <li><big> <a href="#CLAM_HINTS">CLAM Hints and Troubleshooting</a></big></li>
113 <small> </small><big> </big><small> </small>
114 <li><big> <a href="#ACKS">Acknowledgements</a></big></li>
115 <small> </small><small></small>
118 </big><small></small>
120 <hr noshade="noshade" size="8" width="100%"></h2>
121 <small></small></center>
123 </big><small></small>
124 <h2><big><a name="EXECUTIVE_SUMMARY"></a>Executive Summary</big></h2>
125 <small></small></center>
126 <big> The CLAM system is a set of macros and rules
127 for the GNU make program
129 simplifies the creation of executable programs and code
131 Most makefiles that use the CLAM system are ten lines long or
133 Makefiles are stated in terms of a set of special variable names that
135 interprets in order to issue the correct sequence of compilation
137 This document presents a tutorial on the variable names and simple
139 that need to be used with CLAM. Several example makefiles and the
141 reference manual for CLAM are also included.<br>
142 CLAM is part of the Feisty Meow® codebase (<a href="http://feistymeow.org/">http://feistymeow.org/</a>)
144 downloaded from there or through a sourceforge mirror site.<br>
145 In the remainder of the document, we will often
146 refer to CLAM as just "clam".<br>
149 <center><small></small>
151 <hr noshade="noshade" size="8" width="100%"></h2>
152 <small></small></center>
154 </big><small></small>
155 <h2><big><a name="PREPARATION"></a>Preparing Your Computer to Use
157 <small></small></center>
158 <h3><big><a name="STEPS_NEEDED"></a>Necessary Steps:</big></h3>
160 <small> </small><big> </big><small> </small>
161 <li><big>Setting environment variables for clam:</big></li>
162 <small> </small><big> </big><small> </small>
164 <li><big>FEISTY_MEOW_APEX:</big></li>
165 <small> </small><big> </big><small> </small>
167 <small> </small><big> </big><small> </small>
169 <big>DEPRECATED</big>
170 <li><big> **REVISE** out of date... This variable has been needed
172 part of the YETIcode project (at <a href="http://feistymeow.org/">http://feistymeow.org</a>).</big></li>
174 <li><big>The default location for clam is under the FEISTY_MEOW_SCRIPTS directory in a
175 folder named clam.<br>
177 <small> </small><big> </big><small> </small>
178 <li><big>If the yeti root directory is in $HOME/yeti
180 default for FEISTY_MEOW_APEX will work and it doesn't need to be
182 <li><big>Setting the variable:<br>
184 <small> </small><big> </big><small> </small>
186 <small> </small><big> </big><small> </small>
187 <li><big>On Unix (with the bash shell): <span style="font-weight: bold;">export
188 MAKEFLAGS="-I $HOME/yeti/clam"</span></big></li>
189 <small> </small><big> </big><small> </small>
190 <li><big>On win32: <span style="font-weight: bold;">set
191 MAKEFLAGS="-I c:/yeti/clam"</span> (or set this in the
193 control panel, under the advanced tab, in environment variables)<span
194 style="font-weight: bold;"><br>
196 <small> </small><big> </big><small> </small>
197 <li><big>Note that the use of
198 forward slashes is mandatory in the clam directory in MAKEFLAGS.<br>
200 <small> </small><big> </big><small> </small>
202 <small> </small><big> </big><small> </small>
204 <small> </small><big> </big><small> </small>
205 <li><big>MAKEFLAGS:</big></li>
206 <small> </small><big> </big><small> </small>
208 <small> </small><big> </big><small> </small>
209 <li><big> This variable is required to be set in the
210 environment before using clam with gnu-make. It tells make
212 to find the clam definitions and scripts.</big></li>
214 <li><big>Setting the variable:<br>
216 <small> </small><big> </big><small> </small>
218 <small> </small><big> </big><small> </small>
219 <li><big>On Unix (assuming bash as shell): <span style="font-weight: bold;">export
220 MAKEFLAGS="-I $FEISTY_MEOW_APEX/clam"</span></big></li>
221 <small> </small><big> </big><small> </small>
222 <li><big>On win32: <span style="font-weight: bold;">set
223 MAKEFLAGS="-I %FEISTY_MEOW_APEX%/clam"</span></big></li>
224 <small> </small><big> </big><small> </small>
225 <li><big>This variable also requires forward slashes
227 backslashes.</big></li>
228 <small> </small><big> </big><small> </small>
230 <small> </small><big> </big><small> </small>
235 <li><big>Required Tools:</big></li>
236 <small> </small><big> </big><small> </small>
238 <small> </small><big> </big><small> </small>
239 <li><big>The compiler itself:<br>
241 <small> </small><big> </big><small> </small>
243 <small> </small><big> </big><small> </small>
244 <li><big>If you are running GNU/Linux (or almost any other
245 Posix-compliant operating system), then the GNU C/C++ compiler
246 suite is pretty much all that's needed.</big></li>
247 <small> </small><big> </big><small> </small>
249 GNU C/C++ compiler (included in the <a href="http://www.mingw.org/">MinGW</a>
250 toolkit) should be all that's needed for
252 but the Microsoft Visual Studio 6.0-8.0 compilers can be used if
253 available. Compatibility is only guaranteed for vc8
256 <small> </small><big> </big><small> </small>
258 <small> </small><big> </big><small> </small>
259 <li><big>Win32 Unix Tools:</big></li>
260 <small> </small><big> </big><small> </small>
262 <small> </small><big> </big><small> </small>
263 <li><big> If you are running a win32-based product
267 windows xp, etc) then a few additional tools are required...<br>
269 <small> </small><big> </big><small> </small><small></small>
270 <li><big>The recommended GNU utilities are available for
273 package (http://www.mingw.org/).</big></li>
274 <li><big>Note that you will need to add the binaries directory from
276 your path. The PATH variable can be accessed under MS-NT
277 type OSes through the
278 "control panel | system | advanced | environment variables" menu
280 plan to use msys outside of clam, then ensure that
281 the MSYS bin directory is prior to the
282 windows system directory in your path; this causes the Unix "find"
283 command to be used instead of the Windows version.</big></li>
284 <li><big>Alternatively, a similar set of GNU utilities is
286 in the <a href="http://cygwin.com/">Cygwin package</a>, although
287 these tools are no longer recommended and are, in
288 fact, actively deprecated.</big></li>
289 <small> </small><big> </big><small> </small>
291 <small> </small><big> </big><small> </small>
293 <small> </small><big> </big><small> </small>
295 <small> </small><big> </big><small> </small>
296 <li><big>makedep and version_stamper tools:</big></li>
297 <small> </small><big> </big><small> </small>
299 <small> </small><big> </big><small> </small>
300 <li><big>The CLAM_BINARIES directory in the archive has
302 versions of tools used by clam during a build.<br>
304 <small> </small><big> </big><small> </small>
305 <li><big>If you would rather rebuild them from source, then
307 the script "scripts/generator/produce_feisty_meow.sh" will
308 recreate all of these internal tools.<br>
310 <small> </small><big> </big><small> </small>
312 <small> </small><big> </big><small> </small>
314 <small> </small><big> </big><small> </small>
315 <li><big>Third Party Tools Used By or Supported Within clam:</big></li>
316 <small> </small><big> </big><small> </small>
318 <small> </small><big> </big><small> </small>
319 <li><big>wx widgets:</big></li>
320 <small> </small><big> </big><small> </small>
322 <small> </small><big> </big><small> </small>
323 <li><big>home page: http://www.wxwidgets.org/</big></li>
324 <small> </small><big> </big><small> </small>
325 <li><big>As far as the clam team is concerned, this is the
327 portable (and open source) library for graphical user interfaces.<br>
329 <small> </small><big> </big><small> </small>
331 <small> </small><big> </big><small> </small>
332 <li><big>OpenSSL:</big></li>
333 <small> </small><big> </big><small> </small>
335 <small> </small><big> </big><small> </small>
336 <li><big>home page: http://www.openssl.org/</big></li>
337 <small> </small><big> </big><small> </small>
338 <li><big>This is the team's most favorite library for SSL
340 Sockets Layer) and general encryption needs.<br>
342 <small> </small><big> </big><small> </small>
344 <small> </small><big> </big><small> </small>
345 <li><big>cURL:</big></li>
346 <small> </small><big> </big><small> </small>
348 <small> </small><big> </big><small> </small>
349 <li><big>home page: http://curl.haxx.se/</big></li>
350 <small> </small><big> </big><small> </small>
351 <li><big>The curl library rocks(!) and provides a very
353 tools for programmatically interacting with live web pages.<br>
355 <small> </small><big> </big><small> </small>
357 <small> </small><big> </big><small> </small>
359 <small> </small><big> </big><small> </small>
360 <li><big>Other clam Preconditions:</big></li>
361 <small> </small><big> </big><small> </small>
363 <small> </small><big> </big><small> </small>
364 <li><big>Linux platforms:</big></li>
365 <small> </small><big> </big><small> </small>
367 <small> </small><big> </big><small> </small>
368 <li><big>The standard source code repository is a directory
371 in the user's home directory. If you decompress the feisty_meow
372 library archive in your home directory, you should be all set to
373 perform a build.</big></li>
374 <small> </small><big> </big><small> </small>
375 <li><big>See the Feisty Meow Concerns Ltdwebsite for more details about
376 downloading that codebase (<a href="http://feistymeow.org">http://feistymeow.org</a>).<br>
378 <small> </small><big> </big><small> </small>
380 <small></small><small></small>
382 <small> </small><big> </big><small> </small>
384 <small> </small><big> </big><small> </small>
385 <li><big>Win32 platforms:</big></li>
386 <small> </small><big> </big><small> </small>
388 <small> </small><big> </big><small> </small>
389 <li><big>The standard repository for source code is a substituted
390 drive l:, which is where all the other hierarchies start.
392 drive can be mapped to any folder desired using the "subst"
394 (for example, "subst l: c:\build_dir").
396 objects and final products will be generated to the l: drive.</big></li>
397 <small> </small><big> </big><small> </small>
398 <li value="2"><big>Using MS Visual Studio as the Compiler:</big></li>
399 <small> </small><big> </big><small> </small>
401 <small> </small><big> </big><small> </small>
402 <li><big>VS80COMNTOOLS/VS90COMNTOOLS/VS100COMNTOOLS variable:</big></li>
403 <small> </small><big> </big><small> </small>
405 <small> </small><big> </big><small> </small>
406 <li><big>This variable should be automatically created by
407 Visual Studio upon installation. If it isn't, then
409 a bug or you need to restart your current prompt or your
412 <li><big>The paths that clam uses to find compiler binaries
413 is calculated based on this variable.</big></li>
414 <li><big>Older versions of visual studio are currently
415 unsupported because Microsoft constantly rearranges their
417 tools in a non-maintainable way.<br>
420 <li><big>Several other environment variables are required
422 Studio. They can be set up for your current command prompt
424 running "vcvars32.bat" or "vsvars32.bat" (found under
426 compiler's common directory, which varies depending on the
430 <small> </small><big> </big><small> </small>
432 <small> </small><big> </big><small> </small>
434 <small> </small><big> </big><small> </small>
436 <small> </small><small></small>
439 </big><small></small>
441 <hr noshade="noshade" size="8" width="100%"></h2>
442 <small></small></center>
444 </big><small></small>
445 <h2><big><a name="TUTORIAL"></a>CLAM Tutorial</big></h2>
446 <small></small></center>
447 <big> This section provides an overview of
449 works and how you can make it work for you. It is quite brief,
451 should suffice for most common cases of makefiles. For more
453 usage, consult the CLAM Reference section of this document.
455 <h3><big><a name="CAVEATS"></a>Caveats</big></h3>
457 <small> </small><big> </big><small> </small>
458 <li><big>Most of the Unix tools employed in the make process are
459 case-sensitive.
460 This means that they will probably not find any of the clam support if
461 the files have been changed to upper-case names. It also means
463 all code files must match their descriptions in makefiles, letter for
465 And any batch files or executables invoked also need to be in
467 as clam expects them to be.</big></li>
468 <small> </small><big> </big><small> </small>
469 <li><big>A corollary case requirement is that the makefile must
472 "makefile" or "Makefile". These are the Unix standard names and
474 looks for these by default. If you are willing to type "make -f
475 <i>makefile_name</i>",
476 then you can run any makefile. However, the build-ready
478 should be named according to the standard, since the build process
480 look for these automatically.</big></li>
481 <small> </small><small></small>
484 <a name="TUT_BASICS"></a>Basics</big></h3>
485 <big> The C++ Library
486 Automatic Maker system (or CLAM) is defined as a set of
488 (or macro) definitions. These variable definitions are
490 order to compile and link programs. By setting the variables'
492 appropriately, specific products can be generated from the target rules
494 in clam. Both variables and rules are extensible. The
496 procedure for building a clam-based Makefile has four user-defined
500 <small> </small><big> </big><small> </small>
501 <li><big>loading the default variables for clam,</big></li>
502 <small> </small><big> </big><small> </small>
503 <li><big>redefining the default variables where necessary,</big></li>
504 <small> </small><big> </big><small> </small>
505 <li><big>loading the default rule set for clam,</big></li>
506 <small> </small><big> </big><small> </small>
507 <li><big>defining rules that are local to the user's Makefile.</big></li>
508 <small> </small><small></small>
510 <big>Step 4 can usually be omitted unless the project creates
512 whose types are not supported by clam.<br>
513 clam is structured as a directory hierarchy
514 where the root of clam
516 the most general makefile activities. Activities such as
518 into subdirectories and providing support for cleaning up after a make
520 provided at this level. In the remainder of the document, we
522 designate this location with a "$" character to clarify what part of
523 the clam hierarchy we are describing.<br>
524 The root clam
525 support files are mostly language independent, since they are used by
527 varieties of language dependent derived versions of clam. These
529 are generally not of concern unless one is designing a new derived
531 of clam for a language not yet supported.<br>
532 The subdirectories off of the clam root
534 "derived" makefile services, such as C++ or Ada compilation. Each
535 derived clam service implements at least two files to link into the
537 clam system: a variables file and a rules file. The variables
539 the options for the derived make process; by changing the values of
541 different types of targets can be created. The rules file
543 creation of the targets relevant to the programming language being
545 It may be worth noting that clam can be used to
547 any kind of programmatic process--not just compilation. Currently
549 program compilation is the primary goal.
551 <h3><big><a name="TUT_COMMON"></a>Common Files</big></h3>
552 <big> The top-level file called
555 definitions and descriptions of the variables used throughout the clam
556 system. For a non-derived type of make (using only base clam
558 this file should be included near the start of the user's
560 The rules file (stored in "$/rules.def") should be included after the
562 has modified the appropriate variables that will dictate how the make
566 This scheme of including variables at the
567 top and then rules at the bottom of the user's makefile is employed in
568 all clam makefiles. For example, makefiles for C++ compilation
570 same way. The user's C++ makefile includes the C++ variables
572 in a subdirectory called "$/cpp" under the clam root) at the top of the
573 makefile and then includes the C++ rules at the bottom.<br>
574 An example
575 of a C++ makefile is shown below:
578 <small> </small><big> <tt>include cpp/variables.def <br>
582 SOURCE = chaos.cpp checkup.cpp earth_time.cpp guards.cpp istring.cpp \<br>
583 log_base.cpp mutex.cpp occurrence.cpp outcome.cpp
584 outcome_table.cpp \<br>
585 packable.cpp portable.cpp runtime_history.cpp
586 system_outcomes.cpp \<br>
587 utility.cpp version_checker.cpp version_record.cpp<br>
588 TARGETS = basis.lib<br>
590 include cpp/rules.def</tt><br>
591 </big><small></small>
593 <big>The interior of the makefile overrides the TYPE, SOURCE
594 and TARGETS variables for C++ compilation to specify what is to be
596 (basis.lib) and what it consists of (the CPP files mentioned in
598 The PROJECT variable being overridden is actually defined in the
600 a project name is a required feature of all clam makefiles.
602 <h3><big><a name="TUT_IMPORTANT_VARS"></a>Important Variables</big></h3>
603 <big>
604 The clam root directory is pointed to by an internal variable called
606 defined in $/variables.def. This variable is used by the clam
608 to find extra files that might be needed by derived makefile
610 It is important to change this to the appropriate value when you are
611 using the system in a different location. The CLAM_SCRIPTS variable
613 be directly edited in $/variables.def, or it can be overridden in the
615 of the shell running the make, or it can be passed on the command line
618 For C++ compilation, the above example
620 (for basis.lib) contains examples for most of the required
621 elements. Additional elements
622 will be discussed in the examples section or can be found in the
624 The absolutely required variables for C++ are PROJECT, TYPE, SOURCE and
627 <p><big> PROJECT is a variable that
630 of the project being compiled. This should be a word that can
632 be used as a directory name and partial component of filenames.
634 spaces and other unusual punctuation characters are discouraged.
635 All of the project's temporary directories will be created based on
637 variable. This project name should be unique across a full build;
638 otherwise files generated by compiling identical project names will be
641 <p><big> TYPE is a variable that describes
643 of project that is being compiled. This is necessary because it
645 some aspects of the compilation, such as where the compilation products
647 generated. All files generated by compilation are stored in the
649 directory (by default, either "/opt/feistymeow.org/feisty_meow" in Linux or "l:\" in
650 win32). There are three TYPEs supported so far: </big></p>
652 <small> </small><big> </big><small> </small>
653 <li><big>library: indicates that the project will primarily be
657 dynamic libraries.</big></li>
658 <small> </small><big> </big><small> </small>
659 <li><big>application: indicates that the project will create
660 executables.</big></li>
661 <small> </small><big> </big><small> </small>
662 <li><big>test: indicates that the project constructs test
664 <small> </small><small></small>
667 <big>DEPRECATED</big>
670 Projects of the "library" type will
672 an include directory named after the project, such as
674 "/opt/feistymeow.org/feisty_meow/include/basis".
675 The include directory is created as a copy of the headers in the
677 directory . Library projects will also have their final products
679 to the lib or dll subdirectories of the build directory being created.<br>
680 Projects that are of type "application" will
681 have their executables
682 copied to the executable directory in the repository (such as
686 The "test" type of project
687 will be promoted to a subdirectory named after the PROJECT that resides
688 under the test hierarchy in the repository (such as
689 "~/hoople/tests/turbodog").
692 <big>DEPRECATED</big>
693 <p><big> SOURCE is a list of files that
696 in order to create the final products of the project. These can
698 C++ source files (*.cpp), MS-Win32 resource files (*.rc) and other
700 of source files. The list of objects to create will be determined
701 by transforming the list of SOURCE files (such as by turning a file
703 "fud.cpp" into an object called "fud.obj").
705 <p><big> TARGETS is a list of the products
707 to be created by compilation and linking. The suffix of a target
708 is a well established extension, such as ".lib", ".exe"
709 or ".dll" for MS-Win32 compilation products.
711 <h3><big><a name="TUT_VAR_ASSIGN"></a>Variable Assignment Policies</big></h3>
712 <big>
713 The assignment of variable values is mostly straightforward, but it
715 be valuable to provide a refresher. In GNU make, a variable
717 macro) can be assigned using the following syntax:
720 <small> </small><big>FRED = a b c </big><small> </small>
722 <big>This sets the variable named FRED to the value of "a
723 b c". The variable is referred to as $(FRED) when it is being
725 although its name is just FRED.<br>
726 This syntax is fine when the variable is to be
727 defined only once.
728 In many cases though, a variable is already defined and needs to be
730 to instead of redefined. Using the standard equals (=) operator
732 wipe out the previous definition, so a special assignment
736 <small> </small><big>FRED += d e f </big><small> </small>
738 <big>This is quite similar to the C syntax on integers. It
740 FRED will be given a value equal to its old value plus the new
742 In our example, FRED would be equal to "a b c d e f". Note that
745 FRED = $(FRED) d e f
746 (BAD!)<br>
748 This is not allowed in GNU make because it includes a macro's own value
749 in its definition. This causes a badly formed recursive
751 of the variable; a variable dereferencing operation (such
752 as $(FRED)) causes the variable's current value to
753 be resolved, which in turn dereferences any other variables in the
755 Thus, the reference to $(FRED) causes infinite recursion when
757 in the definition of FRED.<br>
759 In the case of variables that <u>must</u>
760 be defined by the user's makefile, the standard assignment operator
761 (via the = character) can
762 be used. This includes the PROJECT, TYPE, SOURCE, and TARGETS
764 Also, any other variables that are set only by the user's makefile can
765 use simple assignment. This category includes LOCAL_LIBS_USED,
766 LIBS_USED and others of similar nature.<br>
767 But several variables are defined partially
768 by clam, then added to within the user's makefile, and then possibly
770 after the user's makefile is processed (by the clam rules file).
771 These variables cannot use
772 standard assignment and must instead use the incremental assignment
774 operator. Variables included in this category are DEFINITIONS,
776 CLEANUPS, and many others.
778 If you are unsure about the type of variable
779 you are defining, then the incremental assignment (+=) operator is
781 to avoid trashing the variable's previous values.<br>
782
783 Note that when variables are "exported", then any make in a subshell
785 inherit the parent shell's value. This can induce some weird
787 for variables that are incrementally constructed with the +=
789 If this seems to be happening, try using the simple assignment operator
791 that variable in the sub-makefile, if this is allowed. In general
793 variables are not exported unless they MUST be seen by shell scripts
795 this does not occur overly frequently.
797 <h3><big><a name="TUT_OPTIONAL_VARS"></a>Optional Variables</big></h3>
798 <big> There are several miscellaneous
800 are useful, either within one's makefiles or when passed to GNU make on
802 line. These are described below.
804 <p><big> LOCAL_LIBS_USED is a list of
806 that are to be linked in with the library or executable being
808 These are specially formatted names; they are just the prefix part of
810 full library name. For example, if you're building a release
812 and want to link in a data structures library "i_adt.lib" (win32) or
813 "libi_adt.a" (Linux), you can specify:
815 LOCAL_LIBS_USED = i_adt
817 The appropriate prefix and suffix will be attached.
819 <p><big> EXTRA_COPIES is a list of files
820 that should be copied to a project's output folder when it is done
821 being compiled. These should be files that are not already
822 copied as the main products, such as extra data or configuration files
823 that belong with an application.
825 <p><big> EXTRA_VERSIONS is a list of
828 also need to be updated to the main build version during a
830 These are usually needed if a project compiles several executable
832 and each one performs version checking. (By default, any project
833 containing a file called "version.ini" will get a version stamp from
837 <h3><big><a name="WRITING_RULES"></a>Writing Your Own Rules</big></h3>
838 <big> One might need to write new rules
841 file types that are not directly supported by clam. There are a
843 of features provided for writing rules, but there are also some
847 All rules in makefiles need to be prefaced
848 with one of the provided "launcher" macros. These are used to
850 that the rules can be properly executed on different platforms;
852 was especially hard to implement for until these macros were developed
853 (due to what appear to be basic defects in the command line
855 All preaching aside, here are the macros:
858 <small> </small><big> </big><small> </small>
859 <li><big>HIDER: Executes a command but hides the
860 invocation. Any
862 still sent to standard out. If a verbose
863 build is being done, then all of the invocations become visible again.</big></li>
864 <small> </small><big> </big><small> </small>
865 <li><big>HIDESH: Executes a shell script but hides the
867 Similar to HIDER but supports scripts specifically.<br>
869 <small> </small><small></small>
871 <big>Here are some examples of using the macros properly.
874 command itself must be contained in single quotes:<br>
876 $(HIDER) $(MIDL) crumpet_server.idl<br>
878 <blockquote><big>MIDL is also a provided macro; it executes the
880 IDL compiler. </big></blockquote>
881 <big>$(HIDESH) $(CLAM_SCRIPTS)/postconditions.sh<br>
883 <blockquote><big>This runs a shell script that handles the end
885 make.</big></blockquote>
887 <a name="TUT_CONCLUSION"></a>Conclusion</big></h3>
888 <big> This tutorial is intended to raise
891 basic usage. Hopefully the reader will now be able to
893 simple makefiles that use . For more aggressive compilation
895 the reference section may be needed; it describes every variable and
897 used in the system. However, it is most likely the case
899 your unsupported compilation needs will also be required by others in
901 future, and it is hoped that you will contribute them to the
902 main-line support. Currently, the appropriate way to do
905 send the makefile code to the <a href="#lib_manager">library
906 administrator</a>, who will include them
907 in the next version of .
909 <center><small></small>
911 <hr noshade="noshade" size="8" width="100%"></h2>
912 <small></small></center>
914 </big><small></small>
915 <h2><big><a name="REFERENCE"></a>CLAM Reference</big></h2>
916 <small></small></center>
918 <a name="LANG_INDEP_VARS"></a><u>Language Independent Variables</u></big></h2>
919 <big> The language independent variables
921 in the file "$/variables.def". They define the overall structure
922 of a make and can usually be overridden to customize how the make is
925 <h4><big>BUILD_BEFORE</big></h4>
926 <big> This is a list of projects that need
929 before this project can be created. The items in the list are
931 as directories that contain a makefile to be run. For example, if
932 an item in BUILD_BEFORE is listed as ?fred?, then the target
934 will be executed. That target changes to the directory 'fred'
936 running the makefile there. The project in the specified
938 is created using make if needed (as determined by that directory's
940 The projects in BUILD_BEFORE are made immediately after the
944 <h4><big>ACTUAL_TARGETS, ACTUAL_FIRST_TARGETS, ACTUAL_LAST_TARGETS</big></h4>
945 <big> See below for TARGETS, FIRST_TARGETS and
948 <h4><big>BUILD_AFTER</big></h4>
949 <big> A list of directory names that
952 into after this project finishes. Each listed directory will have
954 started on any makefile found.<br>
956 <h4><big>BUILD_BEFORE<br>
958 <big> A list of directory names that
960 recursed into before this project
961 starts. Each directory listed will have make started on any
964 <h4><big>MAKEFILE_NAME</big></h4>
965 <big> A variable that specifies the name
968 for all sub-makes. It works with BUILD_BEFORE and
969 BUILD_AFTER and allows the name of the makefile in a
970 subdirectory to be changed to something other than 'makefile'.
972 supports different types of builds which are controlled by different
976 <h4><big>PARAMETER_FILE</big></h4>
977 <big> A file name that is
978 usually found at the root of the repository. The name is
979 often "build.ini", but any name can be used as the parameter file.
980 This file is an extension of the variable set included in
982 and can be used to provide compilation paramters without resorting to
984 command line. This file is associated with a particular build
986 than the support, so different releases will have different build
988 files. On systems supporting version information, the build's
990 number is stored here also.<br>
992 <h4><big>CATCHER</big></h4>
993 <big> A sub-program launcher like HIDESH
994 but this will trap errors it sees and play the build error
995 CLAM_ERROR_SOUND.<br>
997 <h4><big>CLAM_BINARIES</big></h4>
998 <big> This is a folder where the helper
999 binaries for the CLAM makefile system are located. <br>
1001 <h4><big>CLAM_SCRIPTS</big></h4>
1002 <big> This variable points at the location
1003 where the definitions and helper scripts are located. The
1006 but this can be overridden for local installations of .<br>
1008 <h4><big>CLAM_ERROR_SOUND</big></h4>
1009 <big> This is a list of sound files
1010 that should be played when a make stops with an error. It serves
1012 an audible warning that something bad happened.<br>
1014 <h4><big>CLAM_FINISH_SOUND</big></h4>
1015 <big> This is a list of sound files
1016 that should be played when the make has concluded
1017 successfully. It should play when the outer-most make
1018 has seen all targets created as intended.<br>
1020 <h4><big>CLAM_TMP</big></h4>
1021 <big> Specifies the location for temporary
1022 files generated during a make. The default value usually works
1024 This directory will be created if it does not already exist.<br>
1026 <h4><big>CLEANUPS</big></h4>
1027 <big> This is a list of files to be
1030 clean command. They are possibly acquired from the TARGETS
1032 in the user's Makefile, or by language dependent rules for
1034 Additional files can be added to this list by the user's makefile also.
1036 <h4><big>DIRTY_FILE</big></h4>
1037 <big> This variable points at a file that
1039 that some targets have been remade. It is not used at the base
1041 of clam, but language-specific versions might do something special if
1043 were remade (such as put them in a build repository).
1045 <h4><big>FAILURE_FILE</big></h4>
1046 <big> This file is used as a flag that
1049 a make has failed. The particular file used depends on the
1051 name for this makefile. It is cleared at both the beginning and
1055 <h4><big>FIRST_TARGETS</big></h4>
1056 <big> The FIRST_TARGETS are made before
1059 are created and before any executables are compiled. There must
1061 a rule for making every entry in this list, either through implicit
1063 or explicit ones provided by the user's makefile.
1065 <h4><big>FLAG_FILES</big></h4>
1066 <big> This is a list of all the files
1067 that are used for compilation flags. They are whacked at the
1069 and end of a make.<br>
1071 <h4><big>HIDER</big></h4>
1072 <big> This macro is used throughout
1074 commands that are being sent to the operating system. It can be
1075 disabled to allow a verbose make (see the NOISY macro).
1077 <h4><big>HIDESH</big></h4>
1078 <big> Just like HIDER, but this macro is
1080 for launching shell scripts. Some versions of GNU make (like
1082 have problems running scripts which don't arise when running executable
1084 Those problems led to the creation of the HIDESH macro for those
1086 cases. This is not an issue for Unix systems.
1088 <h4><big> LAST_TARGETS</big></h4>
1089 <big> The LAST_TARGETS are made after all
1092 standard targets are made. Their must be a rule for making every
1093 entry in this list, either through implicit rules or explicit ones
1095 by the user's makefile.
1097 <h4><big>NOISY</big></h4>
1098 <big> This variable can be used to cause a
1101 If the variable is non-empty, then all commands will be echoed to
1103 output. Otherwise, the default is to hide the commands that are
1105 and just show the output of running those commands.
1107 <h4><big>OP_SYSTEM</big></h4>
1108 <big> This is a flag that defines the
1111 name. This flag is sometimes used to choose the appropriate tools
1112 per platform or to conditionally compile code for system
1113 dependent interfaces. The available possibilities so far are
1115 OS2, SYSV (System V Unix), DOS, and WIN32. Only UNIX and WIN32
1117 currently very functional.
1119 <h4><big> OTHER_CLEANS</big></h4>
1120 <big> These are targets to execute before
1122 the main clean up during "make clean". These might be targets
1124 contain shell commands to execute as part of clean up or they could
1126 the "clean_subdirs" command (defined below).
1128 <h4><big>PROJECT</big></h4>
1129 <big> This is a variable that provides the
1132 project being compiled. This should be a word that can also be
1134 as a directory name and as a partial component of filenames.
1136 and other unusual punctuation characters are discouraged. All of
1137 the project's temporary directories will be created based on this
1140 <h4><big>FEISTY_MEOW_APEX</big></h4>
1141 <big> Specifies the root directory
1142 for compilation or other building activities. The
1144 is also where source code and final products of compilation reside,
1146 the default is over-ridden (see TARGETS_STORE).<br>
1148 <h4><big>SH & SHELL</big></h4>
1149 <big> These variables both point at a
1152 used for starting commands. SHELL is defined by GNU make, whereas
1155 <h4><big>SUB_FLAG_FILES</big></h4>
1156 <big> This is a list of the compilation
1159 should be destroyed only at the end of a make. They are used for
1161 with submakefiles--makefiles that were invoked by "this" makefile.<br>
1163 <h4><big>SUBMAKE_FLAG</big></h4>
1164 <big> This points to a file whose presence
1167 a "submake" performed some actions. The flag can be interpreted
1169 some language-specific versions of as a reason to set a flag
1174 <h4><big>TARGETS</big></h4>
1175 <big> These are the products to be created
1177 Each item listed in TARGETS should have a rule that knows how to create
1178 that type of file. The language independent system provides very
1179 few suffix based rules. TARGETS is filled in by the user in
1180 their file, but it is not used directly by the
1183 a generated variable called ACTUAL_TARGETS is used.<br>
1185 <h4><big>TARGETS_STORE</big></h4>
1186 <big> This folder is where all generated
1189 be stored. It is usually identical to FEISTY_MEOW_APEX but can be
1191 when the targets should be stored elsewhere.<br>
1193 <h4><big>Version components: major, minor, revision, build<br>
1195 <big> These four variables specify the
1198 particular build. They are usually stored in the
1200 The major and minor versions are the traditional 2.3, 4.0, etc
1202 of release numbers. The revision number is often used to sequence
1204 builds of that particular release, such that build 3.5.127 is the 127th
1206 of the 3.5 release.<br>
1207 A version-tagged file (such as an executable or
1209 library) with any one of the major, minor or revision numbers differing
1211 an installed build is incompatible with the installed build. An
1213 file or dynamic library will not be allowed to load other dynamic
1215 where these numbers differ.<br>
1216 The last version component is misleadingly called
1218 this number specifies the service pack level for a file. Files
1220 versions only differ in the last "build" component are intended to be
1222 with each other. The understanding is that if only that number
1224 then the external interface to the file has not changed, although the
1226 implementation may have.<br>
1228 <h2><big><a name="LANG_INDEP_RULES"></a><u>Language Independent
1229 Rules</u></big></h2>
1230 <big> The file "$/rules.def" uses the
1233 defined in "$/variables.def" together with a set of make rules to
1235 actions during compilation. The rules file should be included in
1236 the user's Makefile after the compilation variables have been
1238 for the project being compiled. The user's own targets should be
1239 placed after the directive that includes "$/rules.def".
1241 <h4><big>%.halt</big></h4>
1242 <big> These targets cause to exit,
1245 something that it considers catastrophic. An example of this
1247 be when finds an inappropriate entry in the list of objects to
1249 allowing a "make clean" on this makefile will delete files that are
1251 not intended. Hence, when finds this kind of usage, it will
1252 stop the make and issue a complaint.
1254 <h4><big>%.make</big></h4>
1255 <big> Used to compile a makefile in a
1258 "%". This rule is employed by the BUILD_BEFORE macro, but can be
1259 used in the user's makefile targets also.
1261 <h2><big><a name="LANG_INDEP_TARGETS"></a><u>Language Independent
1262 Targets</u></big></h2>
1263 <big> The following targets are defined by
1266 <h4><big>all</big></h4>
1267 <big> This is a standard target that is
1270 no particular target is specified at the make command line. It is
1271 an umbrella target that invokes all of the other targets required to
1273 a make. The order in which the major targets are created is:
1276 <small> </small><big> </big><small> </small>
1277 <li><big>FIRST_TARGETS</big></li>
1278 <small> </small><big> </big><small> </small>
1279 <li><big>TARGETS</big></li>
1280 <small> </small><big> </big><small> </small>
1281 <li><big>LAST_TARGETS</big></li>
1282 <small> </small><small></small>
1286 <big> This causes all of the files in
1288 removed and also executes all of the targets in OTHER_CLEANS. The
1289 language dependent system can override some of this behavior or it can
1290 just add more files to the list of CLEANUPS.
1292 <h4><big>clean_subdirs</big></h4>
1293 <big> This is similar to "make_subdirs" in
1296 into the subdirectories in no particular order, but it runs "make
1298 in each of them. This allows a directory hierarchy of projects to
1299 be cleaned with one command.
1301 <h4><big>finish</big></h4>
1302 <big> The "finish" target represents the
1304 of a make, whether successful or not. It reports the time and
1308 <h4><big>rm_links</big></h4>
1309 <big> This target causes all link files in
1312 directory to be deleted. This is only applicable on a Unix
1316 <h4><big>make_subdirs</big></h4>
1317 <big> This target allows a makefile to
1319 all of the subdirectories under the current directory should be scanned
1320 for makefiles and that those makefiles should be executed. If a
1322 does not exist, it is skipped. Note that the subdirectories are
1324 into in no particular order; the order depends on how the operating
1326 decides to list the directories. If the order of make is
1328 use BUILD_BEFORE instead.
1330 <h4><big>start</big></h4>
1331 <big> The "start" target represents the
1333 the make. It reports the time and date (and logs them).
1335 <h2><big><a name="LANG_INDEP_SCRIPTS"></a><u>Language Independent
1336 Files</u></big></h2>
1337 <h4><big>$(PARAMETER_FILE)</big></h4>
1338 <big> This is a special
1339 file that has at least two purposes in . It is the source of
1341 version number that will be stamped on all the appropriate DLLs and
1343 created during a build. It is also a place where build-wide
1345 directives can be included so that they do not have to be passed on the
1347 line. For C++ compilation, this is usually an INI file
1349 FEISTY_MEOW_APEX under the build folder.
1350 Here is a sample parameter file:
1352 <blockquote><big><tt><font size="-1"><big>#\</big></font></tt> <br>
1353 <tt><font size="-1"><big>[version]</big></font></tt> <br>
1354 <tt><font size="-1"><big>major=14</big></font></tt> <br>
1355 <tt><font size="-1"><big>minor=3</big></font></tt> <br>
1356 <tt><font size="-1"><big>revision=140</big></font></tt> <br>
1357 <tt><font size="-1"><big>build=0</big></font></tt> </big><small> </small>
1358 <p><big><tt><font size="-1"><big>DEBUG=t</big></font></tt> <br>
1359 <tt><font size="-1"><big>OPTIMIZE=t</big></font></tt> <br>
1361 <small> </small></blockquote>
1362 <big>Note the bizarre comment at the top of the makefile; this is
1365 the "[version]" section marker. The comment is required because
1367 build parameter file is pulled directly into the makefile code to set
1369 variables after the version stamp. Without a comment in front of
1370 the section, a syntax error would result. The "[version]" section
1371 marker is required because this file is also sometimes treated as a
1373 in order to read the version stamp.<br>
1374 The build version is stored in the first four
1375 entries. Our interpretation of the stamp is standard for "major"
1376 and "minor". We treat the "revision" as a build revision number;
1377 within a release, there will be numerous revisions--one for each new
1379 that is performed. We then treat the "build" entry as a patch
1381 within that particular build. When we perform our version
1383 only the first three entries are compared; the patch level in "build"
1385 considered irrelevant.
1387 This example also specifies that the build
1388 should be a debug style (rather than release) build and that it should
1389 be optimizer. We can also see that
1390 the flags for bounds checker instrumentation and true time
1391 analysis support are commented out.<br>
1393 <h4><big>badness_catcher.sh</big></h4>
1394 <big> Runs the command line passed
1395 in as a sub-shell and looks for error conditions. If an error
1397 the build is stopped and the CLAM_ERROR_SOUND is played.<br>
1399 <h4><big>datestamp.sh</big></h4>
1400 <big> Echoes the time and date. This
1403 file to make the cross-platform difference less annoying.<br>
1405 <h4><big>exit_make.sh</big></h4>
1406 <big> Causes the make to stop dead in its
1409 <h4><big>postconditions.sh</big></h4>
1410 <big> Invoked at the end of the
1412 portion of a make.<br>
1414 <h4><big>preconditions.sh</big></h4>
1415 <big> Invoked at the beginning of the
1416 language-invariant portion of a make.<br>
1418 <h4><big>starter.sh</big></h4>
1419 <big> This shell script executes a command
1422 to it as its parameters and logs error conditions to standard
1424 It's used by the CATCHER macro.
1427 <hr noshade="noshade" size="8" width="100%"></h2>
1429 <a name="CPP_VARS"></a><u>C++ Specific Variables</u></big></h2>
1430 <big> These variables are used throughout
1433 support. They are defined in "$/cpp/variables.def".
1435 <h4><big>BASE_CPU</big></h4>
1436 <big> Allows specification of the
1438 build is targeted for. This is needed when special actions must
1440 taken for different processor types. Valid values currently
1442 m68k (for Motorola 68000 series), m68340 (specifically the 68340),
1443 x86 (intel 386 and upwards), and ppc860 (the PowerPC 860).
1445 <h4><big>BUILD_LIST_FILE</big></h4>
1446 <big> The list of files that must
1447 be rebuilt. This is only used with compilers that support
1449 of multiple source files with one invocation of the compiler (currently
1453 <h4><big>BUILD_WHACK_FILE</big></h4>
1454 <big> A list of object files that must be
1457 the make fails. This is only relevant in the same situations as
1458 BUILD_LIST_FILE.<br>
1460 <h4><big>COMPILER</big></h4>
1461 <big> This variable chooses the specific
1464 for the compiler. Not all operating system choices above are
1466 with the COMPILER choice. The current possibilities include
1467 GNU_LINUX, GNU_WINDOWS, and GNU_DARWIN.
1469 <h4><big>COMPILER_FLAGS</big></h4>
1470 <big> This is the list of flags passed to
1473 and compiler. It is composed of the SYSTEM, the DEFINITIONS, the
1475 and any user-included options. If flags that don't fit one of the
1477 are needed, they can be added here.
1479 <h4><big>CONSOLE_MODE</big></h4>
1480 <big> This causes the program
1481 to be generated as a console application. This is relevant in
1483 (such as win32) where programs have a split personality depending on
1485 they are to have graphical user interfaces or just console interfaces.
1487 <h4><big>DEBUG_FLAGS</big></h4>
1488 <big> These are flags used for generating
1490 versions of object files, such as ones that include debugging code
1492 for gdb) or ones that add code for profiling (e.g., gprof). Possible
1494 in the Sun CenterLine Compiler environment are -g for debugging code
1498 <h4><big>DEFINITIONS</big></h4>
1499 <big> This is a list of compiler flags
1502 value of C or C++ macros. These usually have the format of
1504 but in this particular variable only the <flag> itself should be
1506 (because the compiler option characters ?-D? are added automatically).
1508 <h4><big>DEPENDENCY_ADDITIONS</big></h4>
1509 <big> This is a list of extra flags that
1511 to the auto-dependency tool. The list can vary for each compiler.
1513 <h4><big>DEPS_FILE</big></h4>
1514 <big> This file is where the
1517 is stored. The "makedep" program is used to generate
1519 information for the files listed in SOURCE. During a build, the
1521 is pulled into the actual code of the makefile; this causes the
1523 to be automatically included so that they can dictate the files that
1527 <h4><big>EXTRA_VERSIONS</big></h4>
1528 <big> This is a list of version files that
1530 to be updated to the main build version during a compilation.
1532 are usually needed if a project compiles several executable files, and
1533 each one performs version checking. By default, any project
1535 a file called "version.ini" will get a version stamp from the main
1539 <h4><big>LIBRARIAN_FLAGS</big></h4>
1540 <big> This is a list of flags that are
1542 library creation tool. Sometimes this must be overridden for a
1546 <h4><big>LIBS_USED</big></h4>
1547 <big> These are code libraries that the
1549 depend upon. They are searched for in any of the directories
1551 in the LIBRARY_SEARCH_PATH.
1553 <h4><big>LOAD_FLAG_PREFIX & LOAD_FLAG_SUFFIX</big></h4>
1554 <big> These tell the linker and loader how
1557 the files and where to locate library components. The prefix is listed
1558 on the compilation command line before the object files are listed, and
1559 the suffix after. The prefix should contain information such as the
1561 to be searched for code libraries (although they should be added to
1562 LIBRARY_SEARCH_PATH).
1563 In the suffix definition, actual library loading statements (like
1565 can be included (although they should be listed in a different form in
1566 LIBS_USED or LOCAL_LIBS_USED).
1568 <h4><big>LOCAL_LIBS_USED</big></h4>
1569 <big> The names in this list actually
1572 to be recompiled when the libraries listed have changed. To
1574 this, these libraries MUST be located in the STATIC_LIBRARY_DIR rather
1576 at some arbitrary place on the LIBRARY_SEARCH_PATH. These
1578 also must follow the special naming convention followed by ; if
1580 is an entry in this list, then a library called "basis.lib" will be
1584 <h4><big>NO_COMPILE</big></h4>
1585 <big> Specifies that no compilation
1586 should be performed. Nothing in the SOURCE or TARGETS macros will
1590 <h4><big>NO_DEPS</big></h4>
1591 <big> This is an exclusion flag. If
1594 then no auto-dependency files will be generated. This is useful
1596 you're missing the makedep tool and trying to compile it.<br>
1598 <h4><big>OBJECTS</big></h4>
1599 <big> The OBJECTS are all those files that
1602 created during compilation. Usually this list is filled based on
1603 the files in SOURCE.
1605 <h4><big>OPTIMIZE</big></h4>
1606 <big> Causes the make to create optimized
1608 The default optimization is for speed.
1610 <h4><big>REBUILD</big></h4>
1611 <big> If the REBUILD variable is
1613 files listed in the SOURCE variable are touched. This should
1615 all of those files to be rebuilt during the compilation.
1617 GNU make will complain that a file is newer than the current time, but
1618 this does not usually cause any problems.
1620 <h4><big>SOURCE</big></h4>
1621 <big> The SOURCE variable is a list of
1624 to be compiled in order to create the final products of the
1626 These can be C++ source files (*.cpp), Win32 resource files (*.rc)
1628 other types of source files. The list of objects to create will
1630 determined by transforming the list of SOURCE files (such as by turning
1631 a file called "fud.cpp" into an object called "fud.obj"). More
1633 types will be added as they are needed.
1635 <h4><big>STATIC</big></h4>
1636 <big> Causes the make to create statically
1639 Executables or dynamic libraries will not link in any compiler supplied
1640 dynamic libraries, nor will they require them during run-time.
1642 <h4><big>TYPE</big></h4>
1643 <big> This is a variable that describes
1645 project that is being compiled. Knowing the type of project is
1647 because it controls some elements of the compilation and also of the
1649 promotion of the compiled products. There are three TYPEs
1654 <small> </small><big> </big><small> </small>
1655 <li><big>library: indicates that the project will be primarily
1659 dynamic libraries.</big></li>
1660 <small> </small><big> </big><small> </small>
1661 <li><big>application: indicates that the project will create
1662 executables.</big></li>
1663 <small> </small><big> </big><small> </small>
1664 <li><big>test: indicates that the project constructs test
1665 programs.</big></li>
1666 <small> </small><small></small>
1668 <big>Projects of the "library" type will follow the special
1670 their include directory (which is created as a copy of headers in the
1672 directory). Library projects will also have their final products
1673 copied to the lib or dll subdirectories of the build directory being
1675 Projects that are "application"s will have their executables copied to
1676 the executable directory in the build. And "test" projects will
1678 promoted to a subdirectory named after the PROJECT that resides under
1680 test hierarchy in the build.
1682 <h2><big><a name="DIRECTORY_VARS"></a><u>C++ Directory Structure
1683 Variables</u></big></h2>
1684 <h4><big>BASE_OUTPUT_PATH</big></h4>
1685 <big> This is the parent directory
1686 for object files generated for the specified type of CPU and the style
1688 build (e.g. debug or release builds).<br>
1690 <h4><big>CPU_BUILD_DIR</big></h4>
1691 <big> This variable can be used to
1694 names used for output. It includes the cpu name and the type of
1697 <h4><big>DYNAMIC_LIBRARY_DIR</big></h4>
1698 <big> The directory where dynamic
1700 stored after creation.<br>
1702 <h4><big>EXECUTABLE_DIR</big></h4>
1703 <big> The directory where executable files
1705 stored after creation.<br>
1707 <h4><big>FINAL_DIR</big></h4>
1708 <big> This is the name of the directory
1711 compilation products are stored, currently only import libraries for
1712 dynamic libraries.
1713 It is usually a directory under the OUTPUT_PATH named "final".
1715 <h4><big>HEADER_SEARCH_PATH</big></h4>
1716 <big> This is a list of directories that
1719 for C++ header files (files ending in ?.h?).
1721 <h4><big>HOOPLE_HEADERS</big></h4>
1722 <big>DEPRECATED</big>
1723 <big> The two standard places to look for
1725 (the repository and the third party directory) are listed in this
1728 <h4><big>HOOPLE_LIBRARIES</big></h4>
1729 <big>DEPRECATED</big>
1730 <big> This is where our libraries are
1731 located. It is usually a subdirectory called "lib" under the
1735 <h4><big>LIBRARY_SEARCH_PATH</big></h4>
1736 <big> This is a list of directories that
1739 for C++ library archives (files ending in ".a" or ".lib").
1741 <h4><big>LOCAL_HEADERS</big></h4>
1742 <big> This variable provides a way to
1745 prior to the default locations in the search path. For example,
1747 you are compiling locally and have some headers that are not present in
1748 the build you are using, then you can specify where they are in this
1751 <h4><big>LOCAL_LIBRARIES</big></h4>
1752 <big> This variable allows other library
1754 to be added prior to the default search locations. This enables
1756 static or import libraries to be used instead of the standard ones
1760 <h4><big>STATIC_LIBRARY_DIR</big></h4>
1761 <big> This is the location where code
1763 to be copied during promotion and where they are to be searched for
1765 listed in LOCAL_LIBS_USED. Under Unix, these libraries have a
1767 suffix and are created with the "ar" program. Under Win32,
1769 libraries have a ?.lib? suffix and are created with "link".
1771 <h4><big>OBJECT_DIR</big></h4>
1772 <big> This is where object files will be
1775 compilation for the target type being produced.
1777 <h4><big>OUTPUT_DIRECTORY_LIST</big></h4>
1778 <big> This is a list of directories that
1780 created under the OUTPUT_PATH. It contains the "final" directory
1781 where all finished products are stored, as well as all the intermediate
1782 directories for objects.
1784 <h4><big>OUTPUT_PATH</big></h4>
1785 <big> This is the temporary file storage
1787 Any files that are created during the compilation process will be
1789 under here in a subdirectory named after the PROJECT.
1791 <h4><big>OUTPUT_ROOT</big></h4>
1792 <big> This specifies the root portion of
1795 It lets a PC build use drive letters for the root, while a Unix build
1797 specify a directory hierarchy.
1799 <h4><big>SEARCH_DIRS</big></h4>
1800 <big> This is a list of directories that
1803 for both C++ header files and for C++ code libraries. The items
1805 on SEARCH_DIRS will be added to both the LIBRARY_SEARCH_PATH and the
1806 HEADER_SEARCH_PATH.
1807 The reasoning behind this variable is lost in antiquity.
1809 <h4><big>TESTS_DIR <br>
1811 <big> The directory where test programs
1813 stored after creation.<br>
1815 <h4><big>THIRD_PARTY_DIR</big></h4>
1816 <big> Third party components are sometimes
1819 creation of products. The directory is expected to have a
1821 containing "include" and "lib" subdirectories where headers and
1825 <h2><big><a name="CPP_FLAGS"></a><u>Compiler Dependent Flags</u></big></h2>
1828 <big> This is the name of the C++ compiler
1831 <h4><big>COMPILER_HEADER_DIR</big></h4>
1832 <big> This is where the compiler's header
1835 root directory is located. It is usually based on the root
1838 <h4><big>COMPILER_LIBRARY_DIR</big></h4>
1839 <big> This is where the code libraries for
1842 are located. It is usually based on the root directory.
1844 <h4><big>COMPILER_ROOT_DIR</big></h4>
1845 <big> This should automatically be set to
1848 local directory where the C++ compiler is located.
1850 <h4><big>CREATE_LIBRARY_FLAG</big></h4>
1851 <big> This flag, if required, specifies
1854 must precede the name of a library to create. It is passed to the
1855 library creation tool.
1857 <h4><big>DEF_FILE</big></h4>
1858 <big> This flag only applies to Win32
1860 It specifies the name of a DEF file for all of the products created in
1863 <h4><big>LIB_PREFIX & LIB_SUFFIX</big></h4>
1864 <big> The portions of a library's name
1865 dictated by the operating system. For example, on Unix the prefix
1867 and the suffix is ".a", leading to library names like "libbasis.a" for
1869 basis library. On win32, the prefix is "" and the suffix is
1871 to library names like "basis.lib".<br>
1873 <h4><big>LIBRARY_NAME_FLAG</big></h4>
1874 <big> This flag contains the text that
1877 that will be included in a link. It is often "-l".
1879 <h4><big>LIBRARY_PATH_FLAG</big></h4>
1880 <big> This flag provides the text needed
1883 library search path. Multiple occurrences of this flag followed
1885 a directory name are allowed by most compilers.
1887 <h4><big>LIBRARY_TOOL</big></h4>
1888 <big> This is the name of the program
1893 <h4><big>LINK_TOOL</big></h4>
1894 <big> This is the name of the program that
1896 This is sometimes the same as the compiler (CC) and sometimes the same
1897 as the librarian (LIBRARY_TOOL).
1899 <h4><big>LINKER_OPTION_SEPARATOR</big></h4>
1900 <big> In some compilers, linker options
1903 from compiler options that occur on the same command line. This
1905 serves that purpose.
1907 <h4><big>LINKER_OUTPUT_FLAG</big></h4>
1908 <big> This flag is sometimes required by a
1911 specifying the name of the library or executable that it is creating.
1913 <h4><big>OBJECT_NAME_FLAG</big></h4>
1914 <big> This flag is used to specify the
1917 file being created. It is passed to the compiler to override
1919 default name would be used.
1921 <h2><big><u><a name="vcpp_only"></a>Microsoft-Visual C++ Only</u><br>
1923 <h4><big>USE_MFC</big></h4>
1924 <big> This flag only applies to Visual C++
1927 that MFC is to be used in creating this project. This is usually
1928 the case for GUI applications.
1930 <h4><big>VC_ROOT</big></h4>
1931 <big> This is an override that allows the
1934 directory to be customized without changing the code. If
1936 is set (either in a makefile or as an external variable), then it will
1937 be used in place of the COMPILER_ROOT_DIR. The best way to use
1939 override is as an external environment variable; this allows makefiles
1940 to remain the same despite your local configuration of the compiler.
1942 Note that this variable should use
1944 where DOS/Win32 would use backslashes. Also, if you have
1946 Visual C++ in a directory path containing space characters, then please
1947 use the 8.3 notation for the directories containing the spaces; this
1949 the name to be passed around successfully. For example...
1951 <center><small></small><big> </big><big> </big><big> </big><big> </big><big></big><big></big><big>
1952 </big><big> </big><big> </big><big> </big><big>
1953 </big><big> </big><big> </big><big> </big><small> </small><small></small><small>
1954 </small><small> </small><small> </small><small> </small><small>
1955 </small><small> </small><small> </small><small> </small><small> </small><small></small><small>
1956 </small><small> </small><small> </small><small> </small>
1957 <table cellpadding="8" cellspacing="4">
1960 <td><big> </big><small> </small>
1961 <center><big><u>If Visual C++ Is Installed In</u></big></center>
1962 <small> </small><big> </big></td>
1963 <td><big> </big><small> </small>
1964 <center><big><u>Then VC_ROOT Should Be</u></big></center>
1965 <small> </small><big> </big></td>
1968 <td><big> </big><small> </small>
1969 <center><big>c:\devstudio\vc</big></center>
1970 <small> </small><big> </big></td>
1971 <td><big> </big><small> </small>
1972 <center><big>c:/devstudio/vc</big></center>
1973 <small> </small><big> </big></td>
1976 <td><big> </big><small> </small>
1977 <center><big>c:\program files\devstudio\vc</big></center>
1978 <small> </small><big> </big></td>
1979 <td><big> </big><small> </small>
1980 <center><big>c:/progra~1/devstudio/vc</big></center>
1981 <small> </small><big> </big></td>
1985 <small></small></center>
1986 <h4><big>VCS_ROOT</big></h4>
1987 <big> Similarly to the VC_ROOT, this
1989 at the root of the C# support for Visual Studio.Net.<br>
1991 <h4><big>FRAMEWORK_DIR</big></h4>
1992 <big> This variable specifies the location
1994 .Net framework directory. On MS-Windows XP, the default should be
1995 fine. For MS-Windows 2000 or other Win32 OSes, the windows
1997 should be "winnt" instead. If the operating system is configured
1998 in a non-default way, the framework directory can be specified in an
1999 environment variable.<br>
2001 <h4><big>VCPP_USE_BASE</big></h4>
2002 <big> Specifies that standard Win32
2006 <h4><big>VCPP_USE_GUI</big></h4>
2007 <big> Specifies that the MFC libraries
2011 <h4><big>VCPP_USE_OLE</big></h4>
2012 <big> Specifies that the COM / OLE
2016 <h4><big>VCPP_USE_RPC</big></h4>
2017 <big> Specifies that the MS-RPC libraries
2021 <h4><big>VCPP_USE_SOCK</big></h4>
2022 <big> Specifies that the MS-WinSock
2026 <h2><big><a name="CPP_RULES"></a><u>C++ Specific Rules</u></big></h2>
2027 <big> These types of targets have one
2030 if any of the items that a target depends on in SOURCE or
2032 or included files or whatever have changed since the last time the
2034 was created, then it is recompiled.
2036 <h4><big>%.bad</big></h4>
2037 <big> Causes the make to die. This
2038 is added when an incorrect file type is spotted in a list of targets.<br>
2040 <h4><big>%.dll</big></h4>
2041 <big> These create dynamically linked
2045 <h4><big>%.elf</big></h4>
2046 <big> Creates elf-formatted binaries for
2048 firmware build (a specialized RTOS is the only one currently supported).<br>
2050 <h4><big>%.exe</big></h4>
2051 <big> This creates an executable program
2054 the objects and libraries specified. It is therefore important in
2055 a makefile to only have executables that depend on the same group
2056 of object files. The hidden agenda in the "exe" type of target is
2057 that a file ending in ".cpp" must exist; this is taken as the root of
2059 executable. It should usually contain the main() function (or its
2062 <h4><big>%.lib</big></h4>
2063 <big> This creates static libraries from
2068 <h4><big>%.nil</big></h4>
2069 <big> A blank target for test compiles.<br>
2071 <h4><big>%.obj</big></h4>
2072 <big> These create object files from C++
2075 (files ending in .c or .cpp).
2077 <h4><big>%.res</big></h4>
2078 <big> These create compiled resource files
2083 <h2><big><a name="CPP_TARGETS"></a><u>C++ Specific Targets</u></big></h2>
2085 check_requirements</big></h4>
2086 <big> This target ensures that certain
2088 of the makefile are present. It complains and aborts the make if
2091 <h4><big>post_compilation</big></h4>
2092 <big> This target finalizes the
2095 the postconditions script. If PROMOTE is true, then the final
2097 are copied into the repository.
2099 <h4><big>pre_compilation</big></h4>
2100 <big> This target executes the
2101 preconditions script
2102 to set up the compilation's output directories.
2104 <h4><big>rebuild</big></h4>
2105 <big> This target performs the actions of
2107 This mainly involves touching all of the files in SOURCE before the
2111 <h2><big><a name="CPP_SCRIPTS"></a><u>C++ Specific Files</u></big></h2>
2112 <h4><big>postconditions.sh</big></h4>
2113 <big> After a compilation has succeeded,
2116 script performs the final actions required. The nature of these
2118 depends on the type of project being made. For a library project,
2119 the script copies the headers to the project's include directory and
2121 libraries to the appropriate locations. For application and test
2122 program targets, the script copies the final products to the
2124 repository directory.
2126 <h4><big>preconditions.sh</big></h4>
2127 <big> Before any targets are compiled, the
2129 script ensures that the appropriate output directories exist for the
2131 The script also calls the version utilities to update the project's
2133 file and to create any required resource files.<br>
2135 <h4><big>rebuild_oldies.sh</big></h4>
2136 <big> Used for compilers that support
2139 in one invocation. This is launched to compile a batch of sources
2141 catch any errors.<br>
2143 <hr noshade="noshade" size="8" width="100%">
2144 <center><small></small>
2145 <h2><big><a name="EXAMPLES"></a>CLAM Example Makefiles</big></h2>
2146 <small></small></center>
2147 <big> These examples show some common
2149 how is used. The makefiles below are actually used in real
2153 <h3><big>Library-Only Makefile</big></h3>
2154 <big>This example creates a dynamic library.
2157 <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2159 <p><big><tt>PROJECT = mechanisms</tt><br>
2160 <tt>TYPE = library</tt> <br>
2161 <tt>SOURCE = delayer.cpp eventmgr.cpp event_po.cpp heartbea.cpp
2164 <tt> libmain.cpp monitor.cpp semaphor.cpp state_ma.cpp
2166 time_sta.cpp</tt> <br>
2167 <tt>TARGETS = mechanisms.dll</tt> <br>
2168 <tt>LOCAL_LIBS_USED = basis</tt> <br>
2169 <tt>DEFINITIONS += BUILD_MECHANISMS USE_FEISTY_MEOW_DLLS</tt> </big></p>
2170 <small> </small><big> </big><small> </small>
2171 <p><big><tt>include cpp/rules.def</tt></big></p>
2172 <small> </small><small></small>
2174 <big>The dynamic library created here is mechanisms.dll. The
2177 in also. The file "roller.cpp" will also be copied to the build
2179 include path, presumably since it is a template code file.
2181 <h3><big>Library Plus Executable Makefile</big></h3>
2182 <big>This example shows the basis makefile with a couple of test
2188 <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2190 <p><big><tt>PROJECT = basis</tt> <br>
2191 <tt>TYPE = library</tt> <br>
2192 <tt>SOURCE = chaos.cpp checkup.cpp guards.cpp \</tt> <br>
2193 <tt> istring.cpp itime.cpp logger.cpp matrix.cpp
2194 portable.cpp \</tt> <br>
2195 <tt> realtime.cpp textdump.cpp timezone.cpp utility.cpp \</tt> <br>
2196 <tt> version_checker.cpp version_record.cpp</tt> <br>
2197 <tt>TARGETS = basis.lib t_string.exe t_alloc.exe</tt> </big></p>
2198 <small> </small><big> </big><small> </small>
2199 <p><big><tt>include cpp/rules.def</tt></big></p>
2200 <small> </small><small></small>
2202 <big>Note that the executables
2203 "t_string.exe" and "t_alloc.exe" require files called "t_string.cpp"
2205 "t_alloc.cpp" to exist. These files are expected to contain the
2207 or "WinMain()" functions (or the MFC application object). All of
2209 files in the SOURCE variable will be included in each final executable.
2211 <h3><big>Executable-Only Makefile</big></h3>
2212 <big>This example is produces several test programs that exercise
2218 <small> </small><big> <tt>include cpp/variables.def</tt> </big><small>
2220 <p><big><tt>PROJECT = t_basis</tt> <br>
2221 <tt>TYPE = test</tt> <br>
2222 <tt>SOURCE = instance.cpp t_basis.rc</tt> <br>
2223 <tt>TARGETS = t_alloc.exe t_chaos.exe t_checku.exe t_dattim.exe \</tt>
2225 <tt> t_matrix.exe t_sequen.exe t_sorts.exe t_string.exe \</tt> <br>
2226 <tt> t_texdmp.exe</tt> <br>
2227 <tt>LOCAL_LIBS_USED = basis</tt> </big></p>
2228 <small> </small><big> </big><small> </small>
2229 <p><big><tt>include cpp/rules.def</tt></big></p>
2230 <small> </small><small></small>
2232 <big>The programs "t_alloc.exe" and so on will require C++ files
2235 prefix (t_alloc.cpp) to contain the main program (as in the previous
2237 The items in the SOURCE list will be included in each executable, and
2239 basis library will be linked in.
2241 <h2><big><a name="CLAM_HINTS"></a>CLAM Hints</big></h2>
2242 <big> This section
2243 is devoted to untangling snags that have been encountered in the
2245 Hopefully problems you encounter will be discussed here. Please
2247 any new problems found to the <a href="#lib_manager">library
2250 <h3><big>Problem:</big></h3>
2251 <big> A message like:
2254 <small> </small><big> </big><small> </small>
2256 <small> </small><big>make: *** No rule to make target
2257 `o:/x86_w32_rel/project/final/myproj.dll',
2258 needed by `all'. Stop. </big><small> </small>
2260 <small> </small><small></small>
2262 <big>is displayed during a make.
2264 <h3><big>Solution:</big></h3>
2265 <big> The most frequent reason for
2268 similar to the above is that there is a file listed in SOURCE that
2270 does not exist or that is capitalized differently from how it is
2272 Check that all the files in SOURCE are in the makefile's directory and
2273 that the exact spelling of those files (including their case) is
2276 Another potential cause of this problem is
2277 if a file is included in the SOURCE that does not
2279 The standard compilable files are supported (*.cpp, *.c, *.rc), but it
2280 is possible that a makefile must handle a non-standard extension (such
2281 as *.idl). Either the user's makefile must supply a rule for
2283 this type of file or the user must negotiate with the
2285 to get that type of target added to the support.
2287 <h3><big>Problem:</big></h3>
2288 <big> Clam is complaining about programs
2293 <h3><big>Solution:</big></h3>
2294 <big> The most frequent cause of this
2297 not being on your path. The compilation tools bin (CLAM_BINARIES)
2298 directory must be in
2301 Problems are occasionally seen when the PATH
2302 contains directory names that have spaces in them. Try using the
2303 shorter 8.3 form of the directory name.
2305 An even more obscure situation sometimes
2306 occurs: paths with networked drives seem to somehow hide paths with
2308 are listed later in the PATH variable. The cause of this is
2310 although it was thought to be caused by NetWare at one point. To
2312 the situation, move the local paths before the networked ones.<br>
2315 <hr noshade="noshade" size="8" width="100%">
2316 <center><small></small>
2317 <h2><big><a name="ACKS"></a>Acknowledgements</big></h2>
2318 <small></small></center>
2319 <center><big>Thanks to April Bly Monnen for the wonderful cover
2321 </big><small></small>
2322 <p><big>Thanks to Kevin Wika for some early help with makefiles.
2324 <small></small><big><big>
2325 </big></big><small></small>
2326 <hr noshade="noshade" size="8" width="100%"></center>