C/the.ansi.c.programming.language/notes.accompany.ansi.c/sx7n.html

   1 <!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
   2 <!-- This collection of hypertext pages is Copyright 1995, 1996 by Steve Summit. -->
   3 <!-- This material may be freely redistributed and used -->
   4 <!-- but may not be republished or sold without permission. -->
   5 <html>
   6 <head>
   7 <link rev="owner" href="mailto:scs@eskimo.com">
   8 <link rev="made" href="mailto:scs@eskimo.com">
   9 <title>section 4.11.3: Conditional Inclusion</title>
  10 <link href="sx7m.html" rev=precedes>
  11 <link href="sx8.html" rel=precedes>
  12 <link href="sx7.html" rev=subdocument>
  13 </head>
  14 <body>
  15 <H2>section 4.11.3: Conditional Inclusion</H2>
  16
  17 page 91
  18 <p>The <TT>#if !defined(HDR)</TT> trick is a bit esoteric to start out with.
  19 Let's look at a simpler example:
  20 in ANSI C,
  21 the <TT>remove</TT> function deletes a file.
  22 On some older Unix systems, however,
  23 the function to delete a file is instead named <TT>unlink</TT>.
  24 Therefore, when deleting a file,
  25 we might use code like this:
  26 <pre>   #if defined(unix)
  27                 unlink(filename);
  28         #else
  29                 remove(filename);
  30         #endif
  31 </pre>We would arrange to have the macro <TT>unix</TT>
  32 defined
  33 when we were compiling our program on a Unix machine,
  34 and not otherwise.
  35 </p><p>You may wonder what the difference is between the <TT>if()</TT> statement
  36 we've been using all along,
  37 and this new <TT>#if</TT> preprocessing directive.
  38 <TT>if()</TT> acts at run time;
  39 it selects whether or not a statement or group of statements is executed,
  40 based on a run-time condition.
  41 <TT>#if</TT>, on the other hand,
  42 acts at compile time;
  43 it determines whether certain parts of your program
  44 are even seen by the compiler or not.
  45 If for some reason
  46 you want to have two slightly different versions of your program,
  47 you can use <TT>#if</TT> to separate the different parts,
  48 leaving the bulk of the code common,
  49 such that you don't have
  50 to maintain two totally separate versions.
  51 </p><p><TT>#if</TT> can be used to conditionally compile anything:
  52 not just statements and expressions,
  53 but also declarations and entire functions.
  54 </p><p>Back to the <TT>HDR</TT> example
  55 (though this is somewhat of a tangent,
  56 and it's not vital for you to follow it):
  57 it's possible for the same header file
  58 to be <TT>#include</TT>d twice during one compilation,
  59 either because the same <TT>#include</TT> line appears twice
  60 within the same source file,
  61 or because a source file contains something like
  62 <pre>   #include "a.h"
  63         #include "b.h"
  64 </pre>but <TT>b.h</TT> also <TT>#include</TT>s <TT>a.h</TT>.
  65 Since some declarations
  66 which you might put in header files
  67 would cause errors
  68 if they were acted on twice,
  69 the <TT>#if !defined(HDR)</TT> trick
  70 arranges that the contents of a header file are only processed once.
  71 </p><p>Note that two different macros,
  72 both named <TT>HDR</TT>,
  73 are being used on page 91,
  74 for two entirely different purposes.
  75 At the top of the page,
  76 <TT>HDR</TT> is a simple
  77 on-off
  78 switch;
  79 it is <TT>#define</TT>d
  80 (with no replacement text)
  81 when <TT>hdr.h</TT> is <TT>#include</TT>d for the first time,
  82 and any subsequent #inclusion
  83 merely tests whether <TT>HDR</TT> is <TT>#define</TT>d.
  84 (Note that it is
  85 in fact
  86 quite
  87 possible to define a macro with no replacement text;
  88 a macro so defined
  89 is distinguishable from a macro which has not been <TT>#define</TT>d at all.
  90 One common use of a macro with no replacement text
  91 is precisely as a simple <TT>#if</TT> switch like this.)
  92 </p><p>At the bottom of the page,
  93 <TT>HDR</TT> ends up containing the name of a header file to be <TT>#include</TT>d;
  94 the name depends on the <TT>#if</TT> and <TT>#elif</TT> directives.
  95 The line
  96 <pre>   #include HDR
  97 </pre><TT>#include</TT>s one of them,
  98 depending on the final value of <TT>HDR</TT>.
  99 </p><hr>
 100 <p>
 101 Read sequentially:
 102 <a href="sx7m.html" rev=precedes>prev</a>
 103 <a href="sx8.html" rel=precedes>next</a>
 104 <a href="sx7.html" rev=subdocument>up</a>
 105 <a href="top.html">top</a>
 106 </p>
 107 <p>
 108 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 109 // <a href="copyright.html">Copyright</a> 1995, 1996
 110 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 111 </p>
 112 </body>
 113 </html>