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. -->
12 >Making a Package Distribution</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="Package Organization"
23 HREF="package.html"><LINK
25 TITLE="Package Contents and Layout"
26 HREF="package.contents.html"><LINK
28 TITLE="The CDL Language"
29 HREF="language.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="package.contents.html"
68 >Chapter 2. Package Organization</TD
88 NAME="PACKAGE.DISTRIB">Making a Package Distribution</H1
90 >Developers of new <SPAN
93 > packages are advised to distribute their
94 packages in the form of <SPAN
97 > package distribution files. Packages
98 distributed in this format may be added to existing <SPAN
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
110 NAME="PACKAGE.DISTRIB.FORMAT">The <SPAN
113 > package distribution file format</H2
115 >eCos package distribution files are gzipped GNU tar archives which
116 contain both the source code for one or more <SPAN
120 data file containing package information to be added to the component
121 repository database. The distribution files are subject to the
129 >The data file must be named <TT
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
139 HREF="language.database.html"
140 >the Section called <I
147 describes this data format. Note that a database consistency check is
148 performed by the <SPAN
151 > Administration Tool when
155 > has been appended to the database. Any
156 new target entries which refer to unknown packages will be removed at
161 >The package source code must be placed in one or more <TT
163 ><package-path>/<version></TT
165 directories in the tar archive, where each <package-path>
166 directory path is specified as the directory attribute of one of the
167 packages entries in <TT
174 >An optional license agreement file named
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
185 Administration Tool will then prompt the user with the question
188 >"Do you accept all the terms of the preceding license
190 >. The user must respond
196 > to this prompt in order to proceed with
201 >Optional template files may be placed in one or more <TT
203 >templates/<template_name></TT
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
211 HREF="advanced.html#ADVANCED.TEMPLATES"
212 >the Section called <I
216 information on templates.</P
220 >The distribution file must be given a <TT
227 >) file extension. The
231 > file extension serves to distinguish <SPAN
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
241 Administration Tool lists only those files which have a
249 >No other files should be present in the archive.</P
253 >Files in the tar archive may use <TT
260 > line endings interchangably. The <SPAN
264 Administration Tool ensures that the installed files are given the
265 appropriate host-specific line endings.</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
274 > suffix in addition to any file extension they
275 may already have. For example, the GIF image file
283 > in the archive. The
287 > suffix is removed during file extraction and
288 is used to inhibit the manipulation of line endings by the <SPAN
292 Administration Tool.</P
301 NAME="PACKAGE.DISTRIB.PREPARE">Preparing eCos packages for distribution</H2
303 >Development of new <SPAN
306 > packages or new versions of existing <SPAN
310 packages will take place in the context of an existing <SPAN
314 component repository. This section details the steps involved in
315 extracting new packages from a repository and generating a
319 > package distribution file for distribution of the
320 packages to other <SPAN
323 > users. The steps required are as follows:</P
330 >Create a temporary directory <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
339 > in the repository:</P
348 > $ mkdir -p $PKGTMP/mypkg
349 $ cp -p -R $ECOS_REPOSITORY/mypkg/current $PKGTMP/mypkg</PRE
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
363 >Copy any template files associated with the distributed packages into
364 the temporary directory, preserving the relative path to the template.
374 > $ mkdir -p $PKGTMP/templates
375 $ cp -p -R $ECOS_REPOSITORY/templates/mytemplate $PKGTMP/templates</PRE
382 >Remove any files from the temporary directory hierarchy which you do
383 not want to distribute with the packages (eg object files, <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
405 > $ find $PKGTMP -type f -name '*.gif' -exec mv {} {}.bin ';'</PRE
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
419 >Extract the package records for the new packages from the package
420 database file at <SPAN
422 >$ECOS_REPOSITORY/ecos.db</SPAN
424 create a new file containing these records at
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
434 >Rename the version directories under <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
455 $ mv current v1_0</PRE
461 HREF="package.versions.html"
462 >the Section called <I
463 >Package Versioning</I
465 > describes the version naming
470 >Rename any template files under <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
491 > $ cd $PKGTMP/templates/mytemplate
492 $ mv current.ect v1_0.ect</PRE
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
504 >Optionally create a licence agreement file at
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
514 >Create a GNU tar archive of the temporary directory hierarchy. By
515 convention, this archive would have a name of the form
518 ><package_name>-<version></TT
529 $ tar cf mypkg-1.0.tar *</PRE
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
540 >Compress the archive using gzip and give the resulting file a
553 > $ gzip mypkg-1.0.tar
554 $ mv mypkg-1.0.tar.gz mypkg-1.0.epk</PRE
559 >The resulting eCos package distribution file (*.epk) is in a compressed
560 format and may be distributed without further compression.</P
570 SUMMARY="Footer navigation table"
581 HREF="package.contents.html"
590 HREF="cdl-guide.html"
609 >Package Contents and Layout</TD
623 >The CDL Language</TD