Computed-Includes.html 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1987-2017 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation. A copy of
  7. the license is included in the
  8. section entitled "GNU Free Documentation License".
  9. This manual contains no Invariant Sections. The Front-Cover Texts are
  10. (a) (see below), and the Back-Cover Texts are (b) (see below).
  11. (a) The FSF's Front-Cover Text is:
  12. A GNU Manual
  13. (b) The FSF's Back-Cover Text is:
  14. You have freedom to copy and modify this GNU Manual, like GNU
  15. software. Copies published by the Free Software Foundation raise
  16. funds for GNU development. -->
  17. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  18. <head>
  19. <title>The C Preprocessor: Computed Includes</title>
  20. <meta name="description" content="The C Preprocessor: Computed Includes">
  21. <meta name="keywords" content="The C Preprocessor: Computed Includes">
  22. <meta name="resource-type" content="document">
  23. <meta name="distribution" content="global">
  24. <meta name="Generator" content="makeinfo">
  25. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  26. <link href="index.html#Top" rel="start" title="Top">
  27. <link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
  28. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  29. <link href="Header-Files.html#Header-Files" rel="up" title="Header Files">
  30. <link href="Wrapper-Headers.html#Wrapper-Headers" rel="next" title="Wrapper Headers">
  31. <link href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" rel="prev" title="Alternatives to Wrapper #ifndef">
  32. <style type="text/css">
  33. <!--
  34. a.summary-letter {text-decoration: none}
  35. blockquote.smallquotation {font-size: smaller}
  36. div.display {margin-left: 3.2em}
  37. div.example {margin-left: 3.2em}
  38. div.indentedblock {margin-left: 3.2em}
  39. div.lisp {margin-left: 3.2em}
  40. div.smalldisplay {margin-left: 3.2em}
  41. div.smallexample {margin-left: 3.2em}
  42. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  43. div.smalllisp {margin-left: 3.2em}
  44. kbd {font-style:oblique}
  45. pre.display {font-family: inherit}
  46. pre.format {font-family: inherit}
  47. pre.menu-comment {font-family: serif}
  48. pre.menu-preformatted {font-family: serif}
  49. pre.smalldisplay {font-family: inherit; font-size: smaller}
  50. pre.smallexample {font-size: smaller}
  51. pre.smallformat {font-family: inherit; font-size: smaller}
  52. pre.smalllisp {font-size: smaller}
  53. span.nocodebreak {white-space:nowrap}
  54. span.nolinebreak {white-space:nowrap}
  55. span.roman {font-family:serif; font-weight:normal}
  56. span.sansserif {font-family:sans-serif; font-weight:normal}
  57. ul.no-bullet {list-style: none}
  58. -->
  59. </style>
  60. </head>
  61. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  62. <a name="Computed-Includes"></a>
  63. <div class="header">
  64. <p>
  65. Next: <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="n" rel="next">Wrapper Headers</a>, Previous: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="p" rel="prev">Alternatives to Wrapper #ifndef</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
  66. </div>
  67. <hr>
  68. <a name="Computed-Includes-1"></a>
  69. <h3 class="section">2.6 Computed Includes</h3>
  70. <a name="index-computed-includes"></a>
  71. <a name="index-macros-in-include"></a>
  72. <p>Sometimes it is necessary to select one of several different header
  73. files to be included into your program. They might specify
  74. configuration parameters to be used on different sorts of operating
  75. systems, for instance. You could do this with a series of conditionals,
  76. </p>
  77. <div class="smallexample">
  78. <pre class="smallexample">#if SYSTEM_1
  79. # include &quot;system_1.h&quot;
  80. #elif SYSTEM_2
  81. # include &quot;system_2.h&quot;
  82. #elif SYSTEM_3
  83. &hellip;
  84. #endif
  85. </pre></div>
  86. <p>That rapidly becomes tedious. Instead, the preprocessor offers the
  87. ability to use a macro for the header name. This is called a
  88. <em>computed include</em>. Instead of writing a header name as the direct
  89. argument of &lsquo;<samp>#include</samp>&rsquo;, you simply put a macro name there instead:
  90. </p>
  91. <div class="smallexample">
  92. <pre class="smallexample">#define SYSTEM_H &quot;system_1.h&quot;
  93. &hellip;
  94. #include SYSTEM_H
  95. </pre></div>
  96. <p><code>SYSTEM_H</code> will be expanded, and the preprocessor will look for
  97. <samp>system_1.h</samp> as if the &lsquo;<samp>#include</samp>&rsquo; had been written that way
  98. originally. <code>SYSTEM_H</code> could be defined by your Makefile with a
  99. <samp>-D</samp> option.
  100. </p>
  101. <p>You must be careful when you define the macro. &lsquo;<samp>#define</samp>&rsquo; saves
  102. tokens, not text. The preprocessor has no way of knowing that the macro
  103. will be used as the argument of &lsquo;<samp>#include</samp>&rsquo;, so it generates
  104. ordinary tokens, not a header name. This is unlikely to cause problems
  105. if you use double-quote includes, which are close enough to string
  106. constants. If you use angle brackets, however, you may have trouble.
  107. </p>
  108. <p>The syntax of a computed include is actually a bit more general than the
  109. above. If the first non-whitespace character after &lsquo;<samp>#include</samp>&rsquo; is
  110. not &lsquo;<samp>&quot;</samp>&rsquo; or &lsquo;<samp>&lt;</samp>&rsquo;, then the entire line is macro-expanded
  111. like running text would be.
  112. </p>
  113. <p>If the line expands to a single string constant, the contents of that
  114. string constant are the file to be included. CPP does not re-examine the
  115. string for embedded quotes, but neither does it process backslash
  116. escapes in the string. Therefore
  117. </p>
  118. <div class="smallexample">
  119. <pre class="smallexample">#define HEADER &quot;a\&quot;b&quot;
  120. #include HEADER
  121. </pre></div>
  122. <p>looks for a file named <samp>a\&quot;b</samp>. CPP searches for the file according
  123. to the rules for double-quoted includes.
  124. </p>
  125. <p>If the line expands to a token stream beginning with a &lsquo;<samp>&lt;</samp>&rsquo; token
  126. and including a &lsquo;<samp>&gt;</samp>&rsquo; token, then the tokens between the &lsquo;<samp>&lt;</samp>&rsquo; and
  127. the first &lsquo;<samp>&gt;</samp>&rsquo; are combined to form the filename to be included.
  128. Any whitespace between tokens is reduced to a single space; then any
  129. space after the initial &lsquo;<samp>&lt;</samp>&rsquo; is retained, but a trailing space
  130. before the closing &lsquo;<samp>&gt;</samp>&rsquo; is ignored. CPP searches for the file
  131. according to the rules for angle-bracket includes.
  132. </p>
  133. <p>In either case, if there are any tokens on the line after the file name,
  134. an error occurs and the directive is not processed. It is also an error
  135. if the result of expansion does not match either of the two expected
  136. forms.
  137. </p>
  138. <p>These rules are implementation-defined behavior according to the C
  139. standard. To minimize the risk of different compilers interpreting your
  140. computed includes differently, we recommend you use only a single
  141. object-like macro which expands to a string constant. This will also
  142. minimize confusion for people reading your program.
  143. </p>
  144. <hr>
  145. <div class="header">
  146. <p>
  147. Next: <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="n" rel="next">Wrapper Headers</a>, Previous: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="p" rel="prev">Alternatives to Wrapper #ifndef</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
  148. </div>
  149. </body>
  150. </html>