doc/html/cdl-guide/package.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 >Package Organization</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="PREVIOUS"
  22 TITLE="Warnings"
  23 HREF="overview.warning.html"><LINK
  24 REL="NEXT"
  25 TITLE="Package Versioning"
  26 HREF="package.versions.html"></HEAD
  27 ><BODY
  28 CLASS="CHAPTER"
  29 BGCOLOR="#FFFFFF"
  30 TEXT="#000000"
  31 LINK="#0000FF"
  32 VLINK="#840084"
  33 ALINK="#0000FF"
  34 ><DIV
  35 CLASS="NAVHEADER"
  36 ><TABLE
  37 SUMMARY="Header navigation table"
  38 WIDTH="100%"
  39 BORDER="0"
  40 CELLPADDING="0"
  41 CELLSPACING="0"
  42 ><TR
  43 ><TH
  44 COLSPAN="3"
  45 ALIGN="center"
  46 >The <SPAN
  47 CLASS="APPLICATION"
  48 >eCos</SPAN
  49 > Component Writer's Guide</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="overview.warning.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="package.versions.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="PACKAGE">Chapter 2. Package Organization</H1
  85 ><DIV
  86 CLASS="TOC"
  87 ><DL
  88 ><DT
  89 ><B
  90 >Table of Contents</B
  91 ></DT
  92 ><DT
  93 ><A
  94 HREF="package.html#PACKAGE.HIERARCHY"
  95 >Packages and the Component Repository</A
  96 ></DT
  97 ><DT
  98 ><A
  99 HREF="package.versions.html"
 100 >Package Versioning</A
 101 ></DT
 102 ><DT
 103 ><A
 104 HREF="package.contents.html"
 105 >Package Contents and Layout</A
 106 ></DT
 107 ><DT
 108 ><A
 109 HREF="package.distrib.html"
 110 >Making a Package Distribution</A
 111 ></DT
 112 ></DL
 113 ></DIV
 114 ><P
 115 >For a package to be usable in the <SPAN
 116 CLASS="APPLICATION"
 117 >eCos</SPAN
 118 > component framework it must
 119 conform to certain rules imposed by that framework. Packages must be
 120 distributed in a form that is understood by the component repository
 121 administration tool. There must be a top-level <SPAN
 122 CLASS="APPLICATION"
 123 >CDL</SPAN
 124 > script which
 125 describes the package to the component framework. There are certain
 126 limitations related to how a package gets built, so that the package
 127 can still be used in a variety of host environments. In addition to
 128 these rules, the component framework provides a number of guidelines.
 129 Packages do not have to conform to the guidelines, but sticking to
 130 them can simplify certain operations.</P
 131 ><P
 132 >This chapter deals with the general organization of a package, for
 133 example how to distinguish between private and exported header files.
 134 <A
 135 HREF="language.html"
 136 >Chapter 3</A
 137 > describes the <SPAN
 138 CLASS="APPLICATION"
 139 >CDL</SPAN
 140 > language.
 141 <A
 142 HREF="build.html"
 143 >Chapter 4</A
 144 > details the build process.</P
 145 ><DIV
 146 CLASS="SECT1"
 147 ><H1
 148 CLASS="SECT1"
 149 ><A
 150 NAME="PACKAGE.HIERARCHY">Packages and the Component Repository</H1
 151 ><P
 152 >All <SPAN
 153 CLASS="APPLICATION"
 154 >eCos</SPAN
 155 > installations include a component repository. This is a
 156 directory structure for all installed packages. The component
 157 framework comes with an administration tool that allows new packages
 158 or new versions of a package to be installed, old packages to be
 159 removed, and so on. The component repository includes a simple
 160 database, maintained by the administration tool, which contains
 161 details of the various packages.</P
 162 ><DIV
 163 CLASS="INFORMALFIGURE"
 164 ><A
 165 NAME="AEN187"><P
 166 ></P
 167 ><DIV
 168 CLASS="MEDIAOBJECT"
 169 ><P
 170 ><IMG
 171 SRC="repo.png"
 172 ALIGN="CENTER"></P
 173 ></DIV
 174 ><P
 175 ></P
 176 ></DIV
 177 ><P
 178 >Each package has its own little directory hierarchy within the
 179 component repository. Keeping several packages in a single directory
 180 is illegal. The error, infra and kernel packages all live at the
 181 top-level of the repository. For other types of packages there are
 182 some pre-defined directories: <TT
 183 CLASS="FILENAME"
 184 >compat</TT
 185 > is used for compatibility
 186 packages, which implement other interfaces such as &micro;ITRON or POSIX
 187 using native <SPAN
 188 CLASS="APPLICATION"
 189 >eCos</SPAN
 190 > calls; <TT
 191 CLASS="FILENAME"
 192 >hal</TT
 193 >
 194 is used for packages that port <SPAN
 195 CLASS="APPLICATION"
 196 >eCos</SPAN
 197 > to different architectures or
 198 platforms, and this directory is further organized on a
 199 per-architecture basis; <TT
 200 CLASS="FILENAME"
 201 >io</TT
 202 > is
 203 intended for device drivers; <TT
 204 CLASS="FILENAME"
 205 >language</TT
 206 > is used for language support
 207 libraries, for example the C library. There are no strict rules
 208 defining where new packages should get installed. Obviously if an
 209 existing top-level directory such as <TT
 210 CLASS="FILENAME"
 211 >compat</TT
 212 > is applicable then the new package
 213 should go in there. If a new category is desirable then it is possible
 214 to create a new sub-directory in the component repository. For
 215 example, an organization planning to release a number of <SPAN
 216 CLASS="APPLICATION"
 217 >eCos</SPAN
 218 >
 219 packages may want them all to appear below a sub-directory
 220 corresponding to the organization's name&nbsp;&#8212; in the hope that
 221 the name will not change too often. It is possible to add new packages
 222 directly to the top-level of the component repository, but this should
 223 be avoided.</P
 224 ><P
 225 >The <SPAN
 226 CLASS="DATABASE"
 227 >ecos.db</SPAN
 228 > file holds the component repository
 229 database and is managed by the administration tool. The various
 230 configuration tools read in this file when they start-up to obtain
 231 information about the various packages that have been installed. When
 232 developing a new package it is necessary to add some information to
 233 the file, as described in <A
 234 HREF="language.database.html"
 235 >the Section called <I
 236 >Updating the <SPAN
 237 CLASS="DATABASE"
 238 >ecos.db</SPAN
 239 > database</I
 240 > in Chapter 3</A
 241 >. The
 242 <TT
 243 CLASS="FILENAME"
 244 >templates</TT
 245 > directory holds
 246 various configuration templates.</P
 247 ><DIV
 248 CLASS="NOTE"
 249 ><BLOCKQUOTE
 250 CLASS="NOTE"
 251 ><P
 252 ><B
 253 >Note: </B
 254 >Earlier releases of <SPAN
 255 CLASS="APPLICATION"
 256 >eCos</SPAN
 257 > came with two separate files,
 258 <TT
 259 CLASS="FILENAME"
 260 >targets</TT
 261 > and <TT
 262 CLASS="FILENAME"
 263 >packages</TT
 264 >. The
 265 <SPAN
 266 CLASS="DATABASE"
 267 >ecos.db</SPAN
 268 > database replaces both of these.</P
 269 ></BLOCKQUOTE
 270 ></DIV
 271 ><DIV
 272 CLASS="CAUTION"
 273 ><P
 274 ></P
 275 ><TABLE
 276 CLASS="CAUTION"
 277 BORDER="1"
 278 WIDTH="100%"
 279 ><TR
 280 ><TD
 281 ALIGN="CENTER"
 282 ><B
 283 >Caution</B
 284 ></TD
 285 ></TR
 286 ><TR
 287 ><TD
 288 ALIGN="LEFT"
 289 ><P
 290 >The current <SPAN
 291 CLASS="DATABASE"
 292 >ecos.db</SPAN
 293 > database does not yet provide
 294 all of the information needed by the component framework. Its format
 295 is subject to change in future releases, and the file may be replaced
 296 completely if necessary. There are a number of other likely future
 297 developments related to the component repository and the database. The
 298 way targets are described is subject to change. Sometimes it is
 299 desirable for component writers to do their initial development in a
 300 directory outside the component repository, but there is no specific
 301 support in the framework for that yet.</P
 302 ></TD
 303 ></TR
 304 ></TABLE
 305 ></DIV
 306 ></DIV
 307 ></DIV
 308 ><DIV
 309 CLASS="NAVFOOTER"
 310 ><HR
 311 ALIGN="LEFT"
 312 WIDTH="100%"><TABLE
 313 SUMMARY="Footer navigation table"
 314 WIDTH="100%"
 315 BORDER="0"
 316 CELLPADDING="0"
 317 CELLSPACING="0"
 318 ><TR
 319 ><TD
 320 WIDTH="33%"
 321 ALIGN="left"
 322 VALIGN="top"
 323 ><A
 324 HREF="overview.warning.html"
 325 ACCESSKEY="P"
 326 >Prev</A
 327 ></TD
 328 ><TD
 329 WIDTH="34%"
 330 ALIGN="center"
 331 VALIGN="top"
 332 ><A
 333 HREF="cdl-guide.html"
 334 ACCESSKEY="H"
 335 >Home</A
 336 ></TD
 337 ><TD
 338 WIDTH="33%"
 339 ALIGN="right"
 340 VALIGN="top"
 341 ><A
 342 HREF="package.versions.html"
 343 ACCESSKEY="N"
 344 >Next</A
 345 ></TD
 346 ></TR
 347 ><TR
 348 ><TD
 349 WIDTH="33%"
 350 ALIGN="left"
 351 VALIGN="top"
 352 >Warnings</TD
 353 ><TD
 354 WIDTH="34%"
 355 ALIGN="center"
 356 VALIGN="top"
 357 >&nbsp;</TD
 358 ><TD
 359 WIDTH="33%"
 360 ALIGN="right"
 361 VALIGN="top"
 362 >Package Versioning</TD
 363 ></TR
 364 ></TABLE
 365 ></DIV
 366 ></BODY
 367 ></HTML
 368 >