doc/html/cdl-guide/package.distrib.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 >Making a Package Distribution</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="Package Organization"
  23 HREF="package.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Package Contents and Layout"
  26 HREF="package.contents.html"><LINK
  27 REL="NEXT"
  28 TITLE="The CDL Language"
  29 HREF="language.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  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="package.contents.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 >Chapter 2. Package Organization</TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="language.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><DIV
  84 CLASS="SECT1"
  85 ><H1
  86 CLASS="SECT1"
  87 ><A
  88 NAME="PACKAGE.DISTRIB">Making a Package Distribution</H1
  89 ><P
  90 >Developers of new <SPAN
  91 CLASS="APPLICATION"
  92 >eCos</SPAN
  93 > packages are advised to distribute their
  94 packages in the form of <SPAN
  95 CLASS="APPLICATION"
  96 >eCos</SPAN
  97 > package distribution files. Packages
  98 distributed in this format may be added to existing <SPAN
  99 CLASS="APPLICATION"
 100 >eCos</SPAN
 101 > component
 102 repositories in a robust manner using the Package Administration Tool.
 103 This chapter describes the format of package distribution files and
 104 details how to prepare an eCos package for distribution in this format.</P
 105 ><DIV
 106 CLASS="SECT2"
 107 ><H2
 108 CLASS="SECT2"
 109 ><A
 110 NAME="PACKAGE.DISTRIB.FORMAT">The <SPAN
 111 CLASS="APPLICATION"
 112 >eCos</SPAN
 113 > package distribution file format</H2
 114 ><P
 115 >eCos package distribution files are gzipped GNU tar archives which
 116 contain both the source code for one or more <SPAN
 117 CLASS="APPLICATION"
 118 >eCos</SPAN
 119 > packages and a
 120 data file containing package information to be added to the component
 121 repository database. The distribution files are subject to the
 122 following rules:</P
 123 ><P
 124 ></P
 125 ><OL
 126 TYPE="a"
 127 ><LI
 128 ><P
 129 >The data file must be named <TT
 130 CLASS="FILENAME"
 131 >pkgadd.db</TT
 132 > and must be
 133 located in the root of the tar archive. It must contain data in a
 134 format suitable for appending to the eCos repository database
 135 (<SPAN
 136 CLASS="DATABASE"
 137 >ecos.db</SPAN
 138 >). <A
 139 HREF="language.database.html"
 140 >the Section called <I
 141 >Updating the <SPAN
 142 CLASS="DATABASE"
 143 >ecos.db</SPAN
 144 > database</I
 145 > in Chapter 3</A
 146 >
 147 describes this data format. Note that a database consistency check is
 148 performed by the <SPAN
 149 CLASS="APPLICATION"
 150 >eCos</SPAN
 151 > Administration Tool when
 152 <TT
 153 CLASS="FILENAME"
 154 >pkgadd.db</TT
 155 > has been appended to the database. Any
 156 new target entries which refer to unknown packages will be removed at
 157 this stage.</P
 158 ></LI
 159 ><LI
 160 ><P
 161 >The package source code must be placed in one or more <TT
 162 CLASS="FILENAME"
 163 >&lt;package-path&gt;/&lt;version&gt;</TT
 164 >
 165 directories in the tar archive, where each &lt;package-path&gt;
 166 directory path is specified as the directory attribute of one of the
 167 packages entries in <TT
 168 CLASS="FILENAME"
 169 >pkgadd.db</TT
 170 >.</P
 171 ></LI
 172 ><LI
 173 ><P
 174 >An optional license agreement file named
 175 <TT
 176 CLASS="FILENAME"
 177 >pkgadd.txt</TT
 178 > may be placed in the root of the tar
 179 archive. It should contain text with a maximum line length of 79
 180 characters. If this file exists, the contents will be presented to the
 181 user during installation of the package. The <SPAN
 182 CLASS="APPLICATION"
 183 >eCos</SPAN
 184 > Package
 185 Administration Tool will then prompt the user with the question
 186 <TT
 187 CLASS="PROMPT"
 188 >"Do you accept all the terms of the preceding license
 189 agreement?"</TT
 190 >. The user must respond
 191 <TT
 192 CLASS="USERINPUT"
 193 ><B
 194 >"yes"</B
 195 ></TT
 196 > to this prompt in order to proceed with
 197 the installation.</P
 198 ></LI
 199 ><LI
 200 ><P
 201 >Optional template files may be placed in one or more <TT
 202 CLASS="FILENAME"
 203 >templates/&lt;template_name&gt;</TT
 204 >
 205 directories in the tar archive. Note that such template files would be
 206 appropriate only where the packages to be distributed have a complex
 207 dependency relationship with other packages. Typically, a third party
 208 package can be simply added to an eCos configuration based on an
 209 existing core template and the provision of new templates would not be
 210 appropriate. <A
 211 HREF="advanced.html#ADVANCED.TEMPLATES"
 212 >the Section called <I
 213 >Templates</I
 214 > in Chapter 6</A
 215 > contains more
 216 information on templates.</P
 217 ></LI
 218 ><LI
 219 ><P
 220 >The distribution file must be given a <TT
 221 CLASS="FILENAME"
 222 >.epk</TT
 223 > (not
 224 <TT
 225 CLASS="FILENAME"
 226 >.tar.gz</TT
 227 >) file extension. The
 228 <TT
 229 CLASS="FILENAME"
 230 >.epk</TT
 231 > file extension serves to distinguish <SPAN
 232 CLASS="APPLICATION"
 233 >eCos</SPAN
 234 >
 235 package distributions files from generic gzipped GNU tar archives. It
 236 also discourages users from attempting to extract the package from the
 237 archive manually. The file browsing dialog of the <SPAN
 238 CLASS="APPLICATION"
 239 >eCos</SPAN
 240 > Package
 241 Administration Tool lists only those files which have a
 242 <TT
 243 CLASS="FILENAME"
 244 >.epk</TT
 245 > extension.</P
 246 ></LI
 247 ><LI
 248 ><P
 249 >No other files should be present in the archive.</P
 250 ></LI
 251 ><LI
 252 ><P
 253 >Files in the tar archive may use <TT
 254 CLASS="LITERAL"
 255 >LF</TT
 256 > or
 257 <TT
 258 CLASS="LITERAL"
 259 >CRLF</TT
 260 > line endings interchangably. The <SPAN
 261 CLASS="APPLICATION"
 262 >eCos</SPAN
 263 >
 264 Administration Tool ensures that the installed files are given the
 265 appropriate host-specific line endings.</P
 266 ></LI
 267 ><LI
 268 ><P
 269 >Binary files may be placed in the archive, but the distribution of
 270 object code is not recommended. All binary files must be given a
 271 <TT
 272 CLASS="LITERAL"
 273 >.bin</TT
 274 > suffix in addition to any file extension they
 275 may already have. For example, the GIF image file
 276 <TT
 277 CLASS="FILENAME"
 278 >myfile.gif</TT
 279 > must be named
 280 <TT
 281 CLASS="FILENAME"
 282 >myfile.gif.bin</TT
 283 > in the archive. The
 284 <TT
 285 CLASS="FILENAME"
 286 >.bin</TT
 287 > suffix is removed during file extraction and
 288 is used to inhibit the manipulation of line endings by the <SPAN
 289 CLASS="APPLICATION"
 290 >eCos</SPAN
 291 >
 292 Administration Tool.</P
 293 ></LI
 294 ></OL
 295 ></DIV
 296 ><DIV
 297 CLASS="SECT2"
 298 ><H2
 299 CLASS="SECT2"
 300 ><A
 301 NAME="PACKAGE.DISTRIB.PREPARE">Preparing eCos packages for distribution</H2
 302 ><P
 303 >Development of new <SPAN
 304 CLASS="APPLICATION"
 305 >eCos</SPAN
 306 > packages or new versions of existing <SPAN
 307 CLASS="APPLICATION"
 308 >eCos</SPAN
 309 >
 310 packages will take place in the context of an existing <SPAN
 311 CLASS="APPLICATION"
 312 >eCos</SPAN
 313 >
 314 component repository. This section details the steps involved in
 315 extracting new packages from a repository and generating a
 316 corresponding <SPAN
 317 CLASS="APPLICATION"
 318 >eCos</SPAN
 319 > package distribution file for distribution of the
 320 packages to other <SPAN
 321 CLASS="APPLICATION"
 322 >eCos</SPAN
 323 > users. The steps required are as follows:</P
 324 ><P
 325 ></P
 326 ><OL
 327 TYPE="a"
 328 ><LI
 329 ><P
 330 >Create a temporary directory <TT
 331 CLASS="FILENAME"
 332 >$PKGTMP</TT
 333 > for manipulation of the package
 334 distribution file contents and copy the source files of the new
 335 packages into this directory, preserving the relative path to the
 336 package. In the case of a new package at <TT
 337 CLASS="FILENAME"
 338 >mypkg/current</TT
 339 > in the repository:</P
 340 ><TABLE
 341 BORDER="5"
 342 BGCOLOR="#E0E0F0"
 343 WIDTH="70%"
 344 ><TR
 345 ><TD
 346 ><PRE
 347 CLASS="SCREEN"
 348 >    $ mkdir -p $PKGTMP/mypkg
 349     $ cp -p -R $ECOS_REPOSITORY/mypkg/current $PKGTMP/mypkg</PRE
 350 ></TD
 351 ></TR
 352 ></TABLE
 353 ><P
 354 >Where more than one package is to be distributed in a single package
 355 distribution file, copy each package in the above manner. Note that
 356 multiple packages distributed in a single package distribution file
 357 cannot be installed separately. Where such flexibility is required,
 358 distribution of each new package in separate package distribution files
 359 is recommended.</P
 360 ></LI
 361 ><LI
 362 ><P
 363 >Copy any template files associated with the distributed packages into
 364 the temporary directory, preserving the relative path to the template.
 365 For example:</P
 366 ><TABLE
 367 BORDER="5"
 368 BGCOLOR="#E0E0F0"
 369 WIDTH="70%"
 370 ><TR
 371 ><TD
 372 ><PRE
 373 CLASS="SCREEN"
 374 >    $ mkdir -p $PKGTMP/templates
 375     $ cp -p -R $ECOS_REPOSITORY/templates/mytemplate $PKGTMP/templates</PRE
 376 ></TD
 377 ></TR
 378 ></TABLE
 379 ></LI
 380 ><LI
 381 ><P
 382 >Remove any files from the temporary directory hierarchy which you do
 383 not want to distribute with the packages (eg object files, <TT
 384 CLASS="FILENAME"
 385 >CVS</TT
 386 > directories).</P
 387 ></LI
 388 ><LI
 389 ><P
 390 >Add a <TT
 391 CLASS="FILENAME"
 392 >.bin</TT
 393 > suffix to the name of any binary
 394 files. For example, if the packages contains GIF image files (*.gif)
 395 for documentation purposes, such files must be renamed to *.gif.bin as
 396 follows:</P
 397 ><TABLE
 398 BORDER="5"
 399 BGCOLOR="#E0E0F0"
 400 WIDTH="70%"
 401 ><TR
 402 ><TD
 403 ><PRE
 404 CLASS="SCREEN"
 405 >   $ find $PKGTMP -type f -name '*.gif' -exec mv {} {}.bin ';'</PRE
 406 ></TD
 407 ></TR
 408 ></TABLE
 409 ><P
 410 >The <TT
 411 CLASS="FILENAME"
 412 >.bin</TT
 413 > suffix is removed during file extraction
 414 and is used to inhibit the manipulation of line endings by the eCos
 415 Package Administration Tool.</P
 416 ></LI
 417 ><LI
 418 ><P
 419 >Extract the package records for the new packages from the package
 420 database file at <SPAN
 421 CLASS="DATABASE"
 422 >$ECOS_REPOSITORY/ecos.db</SPAN
 423 > and
 424 create a new file containing these records at
 425 <TT
 426 CLASS="FILENAME"
 427 >$PKGTMP/pkgadd.db</TT
 428 > (in the root of the temporary
 429 directory hierarchy). Any target records which reference the
 430 distributed packages must also be provided in pkgadd.db.</P
 431 ></LI
 432 ><LI
 433 ><P
 434 >Rename the version directories under <TT
 435 CLASS="FILENAME"
 436 >$PKGTMP</TT
 437 > (typically <TT
 438 CLASS="FILENAME"
 439 >current</TT
 440 > during development) to reflect
 441 the versions of the packages you are distributing. For example,
 442 version 1.0 of a package may use the version directory name <TT
 443 CLASS="FILENAME"
 444 >v1_0</TT
 445 >:</P
 446 ><TABLE
 447 BORDER="5"
 448 BGCOLOR="#E0E0F0"
 449 WIDTH="70%"
 450 ><TR
 451 ><TD
 452 ><PRE
 453 CLASS="SCREEN"
 454 >    $ cd $PKGTMP/mypkg
 455     $ mv current v1_0</PRE
 456 ></TD
 457 ></TR
 458 ></TABLE
 459 ><P
 460 ><A
 461 HREF="package.versions.html"
 462 >the Section called <I
 463 >Package Versioning</I
 464 ></A
 465 > describes the version naming
 466 conventions.</P
 467 ></LI
 468 ><LI
 469 ><P
 470 >Rename any template files under <TT
 471 CLASS="FILENAME"
 472 >$PKGTMP</TT
 473 > (typically
 474 <TT
 475 CLASS="FILENAME"
 476 >current.ect</TT
 477 > during development) to reflect the
 478 version of the template you are distributing. For example, version 1.0
 479 of a template may use the filename <TT
 480 CLASS="FILENAME"
 481 >v1_0.ect</TT
 482 >:</P
 483 ><TABLE
 484 BORDER="5"
 485 BGCOLOR="#E0E0F0"
 486 WIDTH="70%"
 487 ><TR
 488 ><TD
 489 ><PRE
 490 CLASS="SCREEN"
 491 >    $ cd $PKGTMP/templates/mytemplate
 492     $ mv current.ect v1_0.ect</PRE
 493 ></TD
 494 ></TR
 495 ></TABLE
 496 ><P
 497 >It is also important to edit the contents of the template file, changing
 498 the version of each referenced package to match that of the packages you
 499 are distributing. This step will eliminate version warnings during the
 500 subsequent loading of the template.</P
 501 ></LI
 502 ><LI
 503 ><P
 504 >Optionally create a licence agreement file at
 505 <TT
 506 CLASS="FILENAME"
 507 >$PKGTMP/pkgadd.txt</TT
 508 > containing the licensing terms
 509 under which you are distributing the new packages. Limit each line in
 510 this file to a maximum of 79 characters.</P
 511 ></LI
 512 ><LI
 513 ><P
 514 >Create a GNU tar archive of the temporary directory hierarchy. By
 515 convention, this archive would have a name of the form
 516 <TT
 517 CLASS="FILENAME"
 518 >&lt;package_name&gt;-&lt;version&gt;</TT
 519 >:</P
 520 ><TABLE
 521 BORDER="5"
 522 BGCOLOR="#E0E0F0"
 523 WIDTH="70%"
 524 ><TR
 525 ><TD
 526 ><PRE
 527 CLASS="SCREEN"
 528 >    $ cd $PKGTMP
 529     $ tar cf mypkg-1.0.tar *</PRE
 530 ></TD
 531 ></TR
 532 ></TABLE
 533 ><P
 534 >Note that non-GNU version of tar may create archive files which exhibit
 535 subtle incompatibilities with GNU tar. For this reason, always use GNU
 536 tar to create the archive file.</P
 537 ></LI
 538 ><LI
 539 ><P
 540 >Compress the archive using gzip and give the resulting file a
 541 <TT
 542 CLASS="FILENAME"
 543 >.epk</TT
 544 > file extension:</P
 545 ><TABLE
 546 BORDER="5"
 547 BGCOLOR="#E0E0F0"
 548 WIDTH="70%"
 549 ><TR
 550 ><TD
 551 ><PRE
 552 CLASS="SCREEN"
 553 >    $ gzip mypkg-1.0.tar
 554     $ mv mypkg-1.0.tar.gz mypkg-1.0.epk</PRE
 555 ></TD
 556 ></TR
 557 ></TABLE
 558 ><P
 559 >The resulting eCos package distribution file (*.epk) is in a compressed
 560 format and may be distributed without further compression.</P
 561 ></LI
 562 ></OL
 563 ></DIV
 564 ></DIV
 565 ><DIV
 566 CLASS="NAVFOOTER"
 567 ><HR
 568 ALIGN="LEFT"
 569 WIDTH="100%"><TABLE
 570 SUMMARY="Footer navigation table"
 571 WIDTH="100%"
 572 BORDER="0"
 573 CELLPADDING="0"
 574 CELLSPACING="0"
 575 ><TR
 576 ><TD
 577 WIDTH="33%"
 578 ALIGN="left"
 579 VALIGN="top"
 580 ><A
 581 HREF="package.contents.html"
 582 ACCESSKEY="P"
 583 >Prev</A
 584 ></TD
 585 ><TD
 586 WIDTH="34%"
 587 ALIGN="center"
 588 VALIGN="top"
 589 ><A
 590 HREF="cdl-guide.html"
 591 ACCESSKEY="H"
 592 >Home</A
 593 ></TD
 594 ><TD
 595 WIDTH="33%"
 596 ALIGN="right"
 597 VALIGN="top"
 598 ><A
 599 HREF="language.html"
 600 ACCESSKEY="N"
 601 >Next</A
 602 ></TD
 603 ></TR
 604 ><TR
 605 ><TD
 606 WIDTH="33%"
 607 ALIGN="left"
 608 VALIGN="top"
 609 >Package Contents and Layout</TD
 610 ><TD
 611 WIDTH="34%"
 612 ALIGN="center"
 613 VALIGN="top"
 614 ><A
 615 HREF="package.html"
 616 ACCESSKEY="U"
 617 >Up</A
 618 ></TD
 619 ><TD
 620 WIDTH="33%"
 621 ALIGN="right"
 622 VALIGN="top"
 623 >The CDL Language</TD
 624 ></TR
 625 ></TABLE
 626 ></DIV
 627 ></BODY
 628 ></HTML
 629 >