doc/html/cdl-guide/ref.include-dir.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >include_dir</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="implements"
  26 HREF="ref.implements.html"><LINK
  27 REL="NEXT"
  28 TITLE="include_files"
  29 HREF="ref.include-files.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="ref.implements.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.include-files.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.INCLUDE-DIR"><SPAN
  86 CLASS="PROPERTY"
  87 >include_dir</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4534"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >include_dir</SPAN
  99 >&nbsp;--&nbsp;Specify the desired location of a package's exported
 100 header files in the install tree.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN4538"><H2
 105 >Synopsis</H2
 106 ><TABLE
 107 BORDER="5"
 108 BGCOLOR="#E0E0F0"
 109 WIDTH="70%"
 110 ><TR
 111 ><TD
 112 ><PRE
 113 CLASS="SYNOPSIS"
 114 >cdl_package &lt;name&gt; {
 115     include_dir &lt;sub-directory&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN4540"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >Most packages export one or more header files defining their public
 131 interface. For example the C library exports header files such as
 132 <TT
 133 CLASS="FILENAME"
 134 >stdio.h</TT
 135 > and
 136 <TT
 137 CLASS="FILENAME"
 138 >ctype.h</TT
 139 >.
 140 If the package follows the <A
 141 HREF="package.html#PACKAGE.HIERARCHY"
 142 >directory
 143 layout conventions</A
 144 > then the exported header files will normally
 145 be found in the package's
 146 <TT
 147 CLASS="FILENAME"
 148 >include</TT
 149 > sub-directory.
 150 Alternatively the <SPAN
 151 CLASS="PROPERTY"
 152 >include_files</SPAN
 153 > property can be used to specify
 154 which header files should be exported.</P
 155 ><P
 156 >By default a package's exported header files will be copied to
 157 the <TT
 158 CLASS="FILENAME"
 159 >include</TT
 160 > sub-directory of
 161 the install tree. This is correct for packages like the C library
 162 because that is the correct location for files such as
 163 <TT
 164 CLASS="FILENAME"
 165 >stdio.h</TT
 166 >. However to reduce the
 167 probability of name clashes it is desirable for packages to use
 168 different sub-directories, for example infrastructure header files get
 169 copied to <TT
 170 CLASS="FILENAME"
 171 >include/cyg/infra</TT
 172 >
 173 rather than to the top-level
 174 <TT
 175 CLASS="FILENAME"
 176 >include</TT
 177 > directory itself.</P
 178 ><P
 179 >It would be possible to replicate these sub-directories in each
 180 package's source tree, such that the infrastructure header file
 181 sources lived in
 182 <TT
 183 CLASS="FILENAME"
 184 >include/cyg/infra</TT
 185 > in the source
 186 tree as well as in the install tree. This would make things more
 187 difficult for the package developers. Instead it is possible to
 188 specify the desired install tree sub-directory using an <SPAN
 189 CLASS="PROPERTY"
 190 >include_dir</SPAN
 191 >
 192 property, for example <TT
 193 CLASS="LITERAL"
 194 >include_dir&nbsp;cyg/infra</TT
 195 >.</P
 196 ><P
 197 >The <SPAN
 198 CLASS="PROPERTY"
 199 >include_dir</SPAN
 200 > property can only be used in the body of a
 201 <TT
 202 CLASS="LITERAL"
 203 >cdl_package</TT
 204 > command, since it applies to all of the header files
 205 exported by a package, and only one <SPAN
 206 CLASS="PROPERTY"
 207 >include_dir</SPAN
 208 > property can be
 209 used. If there is no <SPAN
 210 CLASS="PROPERTY"
 211 >include_dir</SPAN
 212 > property then exported header files
 213 will end up in the top-level <TT
 214 CLASS="FILENAME"
 215 >include</TT
 216 >
 217 directory of the install tree.</P
 218 ></DIV
 219 ><DIV
 220 CLASS="REFSECT1"
 221 ><A
 222 NAME="AEN4563"
 223 ></A
 224 ><H2
 225 >Example</H2
 226 ><TABLE
 227 BORDER="5"
 228 BGCOLOR="#E0E0F0"
 229 WIDTH="70%"
 230 ><TR
 231 ><TD
 232 ><PRE
 233 CLASS="PROGRAMLISTING"
 234 >cdl_package CYGPKG_INFRA {
 235     display       "Infrastructure"
 236     include_dir   cyg/infra
 237     description   "
 238         Common types and useful macros.
 239         Tracing and assertion facilities.
 240         Package startup options."
 241     &#8230;
 242 }</PRE
 243 ></TD
 244 ></TR
 245 ></TABLE
 246 ></DIV
 247 ><DIV
 248 CLASS="REFSECT1"
 249 ><A
 250 NAME="AEN4566"
 251 ></A
 252 ><H2
 253 >See Also</H2
 254 ><P
 255 >Property <A
 256 HREF="ref.include-files.html"
 257 ><SPAN
 258 CLASS="PROPERTY"
 259 >include_files</SPAN
 260 ></A
 261 >, and
 262 command <A
 263 HREF="ref.cdl-package.html"
 264 ><TT
 265 CLASS="LITERAL"
 266 >cdl_package</TT
 267 ></A
 268 >.</P
 269 ></DIV
 270 ><DIV
 271 CLASS="NAVFOOTER"
 272 ><HR
 273 ALIGN="LEFT"
 274 WIDTH="100%"><TABLE
 275 SUMMARY="Footer navigation table"
 276 WIDTH="100%"
 277 BORDER="0"
 278 CELLPADDING="0"
 279 CELLSPACING="0"
 280 ><TR
 281 ><TD
 282 WIDTH="33%"
 283 ALIGN="left"
 284 VALIGN="top"
 285 ><A
 286 HREF="ref.implements.html"
 287 ACCESSKEY="P"
 288 >Prev</A
 289 ></TD
 290 ><TD
 291 WIDTH="34%"
 292 ALIGN="center"
 293 VALIGN="top"
 294 ><A
 295 HREF="cdl-guide.html"
 296 ACCESSKEY="H"
 297 >Home</A
 298 ></TD
 299 ><TD
 300 WIDTH="33%"
 301 ALIGN="right"
 302 VALIGN="top"
 303 ><A
 304 HREF="ref.include-files.html"
 305 ACCESSKEY="N"
 306 >Next</A
 307 ></TD
 308 ></TR
 309 ><TR
 310 ><TD
 311 WIDTH="33%"
 312 ALIGN="left"
 313 VALIGN="top"
 314 ><SPAN
 315 CLASS="PROPERTY"
 316 >implements</SPAN
 317 ></TD
 318 ><TD
 319 WIDTH="34%"
 320 ALIGN="center"
 321 VALIGN="top"
 322 ><A
 323 HREF="reference.html"
 324 ACCESSKEY="U"
 325 >Up</A
 326 ></TD
 327 ><TD
 328 WIDTH="33%"
 329 ALIGN="right"
 330 VALIGN="top"
 331 ><SPAN
 332 CLASS="PROPERTY"
 333 >include_files</SPAN
 334 ></TD
 335 ></TR
 336 ></TABLE
 337 ></DIV
 338 ></BODY
 339 ></HTML
 340 >