Changes between Initial Version and Version 1 of EncapManEncapProfile


Ignore:
Timestamp:
08/11/06 07:13:45 (16 years ago)
Author:
dclark
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • EncapManEncapProfile

    v1 v1  
     1{{{ 
     2#!html 
     3<H2>NAME</H2> 
     4 
     5encap_profile - Encap package creation information 
     6<A NAME="lbAC">&nbsp;</A> 
     7<H2>VERSION</H2> 
     8 
     9This man page documents version 1.0 of the Encap profile format. 
     10<A NAME="lbAD">&nbsp;</A> 
     11<H2>DESCRIPTION</H2> 
     12 
     13Encap profiles contain all the information needed to build an Encap 
     14package.  The profile is an XML document. 
     15<A NAME="lbAE">&nbsp;</A> 
     16<H3>THE BASICS OF XML</H3> 
     17 
     18As with any XML document, the first line of the profile must be: 
     19<P> 
     20<DL COMPACT><DT><DD> 
     21&lt;?xml version=&quot;1.0&quot;?&gt; 
     22</DL> 
     23 
     24<P> 
     25An XML element with content looks like this: 
     26<P> 
     27<DL COMPACT><DT><DD> 
     28<PRE> 
     29&lt;element attribute=&quot;value&quot; ...&gt; 
     30  content 
     31&lt;/element&gt; 
     32</PRE> 
     33 
     34</DL> 
     35 
     36<P> 
     37An empty element looks like this: 
     38<P> 
     39<DL COMPACT><DT><DD> 
     40&lt;element attribute=&quot;value&quot; ... /&gt; 
     41</DL> 
     42 
     43<P> 
     44Element names are case-sensitive. 
     45<P> 
     46The &quot;&lt;&quot; and &quot;&gt;&quot; characters need to be replaced with predefined entity 
     47tags &quot;&amp;lt;&quot; and &quot;&amp;gt;&quot; when they're not part of an element tag, just 
     48like in HTML.  However, for whole blocks of text that may contain 
     49these special characters, you can enclose them like this: 
     50<P> 
     51<DL COMPACT><DT><DD> 
     52<PRE> 
     53&lt;![CDATA[ 
     54   echo foo &gt; output 
     55]]&gt; 
     56</PRE> 
     57 
     58</DL> 
     59 
     60<P> 
     61If for some reason you need to include the &quot;]]&gt;&quot; string within a CDATA 
     62section, you can replace the &quot;&gt;&quot; with its entity tag, just like you'd 
     63do outside of a CDATA section (i.e., &quot;]]&amp;gt;&quot;). 
     64<P> 
     65The XML comment delimiters are &quot;&lt;!--&quot; and &quot;--&gt;&quot;. 
     66<A NAME="lbAF">&nbsp;</A> 
     67<H3>PROFILE STRUCTURE</H3> 
     68 
     69Here's a high-level summary of the hierarchical relationship of the 
     70elements described below: 
     71<P> 
     72<DL COMPACT><DT><DD> 
     73<PRE> 
     74&lt;encap_profile&gt; 
     75   &lt;notes&gt; 
     76   &lt;ChangeLog&gt; 
     77      &lt;change&gt; 
     78   &lt;prereq&gt; 
     79   &lt;environment&gt; 
     80   &lt;prepare&gt; 
     81   &lt;source&gt; 
     82      &lt;unpack&gt; 
     83      &lt;patch&gt; 
     84      &lt;configure&gt; 
     85      &lt;build&gt; 
     86      &lt;install&gt; 
     87      &lt;clean&gt; 
     88   &lt;prepackage&gt; 
     89   &lt;include_file&gt; 
     90   &lt;encapinfo&gt; 
     91</PRE> 
     92 
     93</DL> 
     94 
     95<A NAME="lbAG">&nbsp;</A> 
     96<H3>The &lt;encap_profile&gt; Element</H3> 
     97 
     98The <I>&lt;encap_profile&gt;</I> element is the root XML element of the package 
     99profile.  All other elements must be contained within the 
     100<I>&lt;encap_profile&gt;</I> element. 
     101<P> 
     102The <I>&lt;encap_profile&gt;</I> element supports the following attributes: 
     103<DL COMPACT> 
     104<DT><I>profile_ver</I> 
     105 
     106<DD> 
     107Indicates what version of the Encap Profile format is being used. 
     108This attribute is mandatory and must have the value &quot;1.0&quot;. 
     109<DT><I>pkgspec</I> 
     110 
     111<DD> 
     112Sets the full name of the package to be created.  This attribute is 
     113mandatory. 
     114</DL> 
     115<P> 
     116 
     117Example: 
     118<P> 
     119<DL COMPACT><DT><DD> 
     120<PRE> 
     121&lt;encap_profile profile_ver=&quot;1.0&quot; pkgspec=&quot;foo-1.0+1&quot;&gt; 
     122   ... 
     123&lt;/encap_profile&gt; 
     124</PRE> 
     125 
     126</DL> 
     127 
     128<A NAME="lbAH">&nbsp;</A> 
     129<H3>The &lt;notes&gt; Element</H3> 
     130 
     131This optional element may contain arbitrary text.  It is intended to 
     132store README-style notes. 
     133<P> 
     134Example: 
     135<P> 
     136<DL COMPACT><DT><DD> 
     137<PRE> 
     138&lt;notes&gt; 
     139  These are human-readable notes about a profile. 
     140&lt;/notes&gt; 
     141</PRE> 
     142 
     143</DL> 
     144 
     145<A NAME="lbAI">&nbsp;</A> 
     146<H3>The &lt;ChangeLog&gt; and &lt;change&gt; Elements</H3> 
     147 
     148The <I>&lt;ChangeLog&gt;</I> element is composed of one or more <I>&lt;change&gt;</I> 
     149elements that document changes to the profile.  The <I>&lt;ChangeLog&gt;</I> 
     150element itself supports no attributes. 
     151<P> 
     152The <I>&lt;change&gt;</I> element supports the following attributes: 
     153<DL COMPACT> 
     154<DT><I>date</I> 
     155 
     156<DD> 
     157Optional.  Indicates the date of the ChangeLog entry. 
     158<DT><I>version</I> 
     159 
     160<DD> 
     161Required.  Indicates the version of the package to which the ChangeLog 
     162entry applies. 
     163</DL> 
     164<P> 
     165 
     166Example: 
     167<P> 
     168<DL COMPACT><DT><DD> 
     169<PRE> 
     170&lt;ChangeLog&gt; 
     171  &lt;change version=&quot;1.0+1&quot;&gt; 
     172    Fixed a bug in the postinstall script from version 1.0. 
     173  &lt;/change&gt; 
     174  &lt;change version=&quot;1.0&quot;&gt; 
     175    Initial release. 
     176  &lt;/change&gt; 
     177&lt;/ChangeLog&gt; 
     178</PRE> 
     179 
     180</DL> 
     181 
     182<A NAME="lbAJ">&nbsp;</A> 
     183<H3>The &lt;prereq&gt; Element</H3> 
     184 
     185The <I>&lt;prereq&gt;</I> element specifies a build-time prerequisite package. 
     186It may be specified zero or more times, but must be empty.  It supports 
     187the following attributes: 
     188<DL COMPACT> 
     189<DT><I>package</I> 
     190 
     191<DD> 
     192Required.  Specifies the pkgspec of the required package. 
     193<DT><I>use_bin</I> 
     194 
     195<DD> 
     196Optional.  If set to &quot;yes&quot;, prepends <I>package</I>'s <I>bin</I> subdirectory 
     197to the <B>PATH</B> environment variable. 
     198<DT><I>use_lib</I> 
     199 
     200<DD> 
     201Optional.  If set to &quot;yes&quot;, adds <I>package</I>'s <I>include</I> and 
     202<I>lib</I> subdirectories to the <B>CPPFLAGS</B> and <B>LDFLAGS</B> 
     203environment variables. 
     204</DL> 
     205<P> 
     206 
     207Example: 
     208<P> 
     209<DL COMPACT><DT><DD> 
     210&lt;prereq package=&quot;bar-2.5.1&quot; /&gt; 
     211</DL> 
     212 
     213<A NAME="lbAK">&nbsp;</A> 
     214<H3>The &lt;environment&gt; Element</H3> 
     215 
     216Specifies an environment setting.  It may be specified zero or more 
     217times, but must be empty.  It supports the following attributes: 
     218<DL COMPACT> 
     219<DT><I>variable</I> 
     220 
     221<DD> 
     222Required.  The name of the environment variable. 
     223<DT><I>value</I> 
     224 
     225<DD> 
     226Optional.  The new value for the variable. 
     227<DT><I>type<TT>&nbsp;&nbsp;&nbsp;&nbsp;</TT></I> 
     228 
     229<DD> 
     230Optional.  Specifies how the value should be interpretted.  If set<BR> 
     231to &quot;prepend&quot;, the value is prepended to the existing value.  If set to 
     232&quot;append&quot;, the content is appended to the existing value.  If set to &quot;set&quot;, 
     233the value completely replaces the existing value.  If set to &quot;unset&quot;, 
     234the variable is unset.  The default is &quot;set&quot;. 
     235</DL> 
     236<P> 
     237 
     238Example: 
     239<P> 
     240<DL COMPACT><DT><DD> 
     241<PRE> 
     242&lt;environment 
     243        variable=&quot;PATH&quot; 
     244        value=&quot;:/usr/local/bin&quot; 
     245        type=&quot;append&quot; 
     246/&gt; 
     247</PRE> 
     248 
     249</DL> 
     250 
     251<P> 
     252See the <B>ENVIRONMENT VARIABLES</B> section below for more information 
     253on how environment variables are set and used. 
     254<A NAME="lbAL">&nbsp;</A> 
     255<H3>The &lt;prepare&gt; Element</H3> 
     256 
     257The <I>&lt;prepare&gt;</I> element specifies a set of commands to be executed 
     258before any <I>&lt;source&gt;</I> elements are processed.  It supports the 
     259following attributes: 
     260<DL COMPACT> 
     261<DT><I>type</I> 
     262 
     263<DD> 
     264Optional.  Specifies how the contents should be interpretted.  If set to 
     265&quot;prepend&quot;, the content is executed before the existing prepare action. 
     266If set to &quot;append&quot;, the content is executed after the existing prepare 
     267action.  If set to &quot;set&quot;, the contents are executed instead of the existing 
     268prepare action.  If set to &quot;unset&quot;, the prepare action is unset. 
     269The default is &quot;set&quot;. 
     270</DL> 
     271<P> 
     272 
     273The prepare action is executed in whatever directory <B>mkencap</B>  
     274was invoked in.  By default, no prepare commands are executed. 
     275<P> 
     276See <B>COMMAND ELEMENTS</B> below for more information on how the 
     277<I>&lt;prepare&gt;</I> commands are executed. 
     278<A NAME="lbAM">&nbsp;</A> 
     279<H3>The &lt;source&gt; Element</H3> 
     280 
     281Specifies a source (which in this context means &quot;anything you need to 
     282download to build the package&quot;).  It may be specified multiple times, 
     283but must be specified at least once.  It supports the following 
     284attributes: 
     285<DL COMPACT> 
     286<DT><I>url</I> 
     287 
     288<DD> 
     289Required.  A whitespace-delimited list of one or more URLs where the 
     290source can be downloaded. 
     291<P> 
     292Note that the basename of each URL in the list must be the same.  No 
     293checking is done to ensure that they do not differ, but the results are 
     294undefined if they are not identical. 
     295<DT><I>subdir</I> 
     296 
     297<DD> 
     298Optional.  The name of the subdirectory into which the source files will 
     299be unpacked (if different from the name of the source archive). 
     300<DT><I>create_subdir </I> 
     301 
     302<DD> 
     303If set to &quot;yes&quot;, the subdirectory specified by the &quot;subdir&quot; attribute 
     304is created and cd'd to before running the unpack action (see below). 
     305The default is &quot;no&quot;. 
     306<DT><I>build_subdir</I> 
     307 
     308<DD> 
     309Optional.  If set, it denotes a relative path from the source directory 
     310where the configure, build, install, and clean actions are invoked. 
     311<DT><I>use_objdir</I> 
     312 
     313<DD> 
     314Set to &quot;yes&quot; or &quot;no&quot; to indicate whether software can be built in 
     315an objdir.  Defaults to &quot;yes&quot;. 
     316</DL> 
     317<P> 
     318 
     319The &lt;source&gt; element contains zero or more of the following elements, 
     320which are described below: 
     321<DL COMPACT> 
     322<DT>*<DD> 
     323<I>&lt;unpack&gt;</I> 
     324 
     325<DT>*<DD> 
     326<I>&lt;patch&gt;</I> 
     327 
     328<DT>*<DD> 
     329<I>&lt;configure&gt;</I> 
     330 
     331<DT>*<DD> 
     332<I>&lt;build&gt;</I> 
     333 
     334<DT>*<DD> 
     335<I>&lt;install&gt;</I> 
     336 
     337<DT>*<DD> 
     338<I>&lt;clean&gt;</I> 
     339 
     340</DL> 
     341<P> 
     342 
     343Example: 
     344<P> 
     345<DL COMPACT><DT><DD> 
     346<PRE> 
     347&lt;source 
     348   url=&quot;<A HREF="ftp://ftp.isc.org/isc/bind-8.3.3/bind-src.tar.gz">ftp://ftp.isc.org/isc/bind-8.3.3/bind-src.tar.gz</A>&quot; 
     349   subdir=&quot;bind-8.3.3&quot; 
     350   use_objdir=&quot;no&quot; 
     351/&gt; 
     352</PRE> 
     353 
     354</DL> 
     355 
     356<A NAME="lbAN">&nbsp;</A> 
     357<H3>The &lt;unpack&gt; Element</H3> 
     358 
     359Specifies a set of shell commands to use to unpack the source 
     360archives.  The following attributes are supported: 
     361<DL COMPACT> 
     362<DT><I>type</I> 
     363 
     364<DD> 
     365Optional.  Specifies how the contents should be interpretted.  If set 
     366to &quot;prepend&quot;, the content is executed before the existing unpack 
     367action.  If set to &quot;append&quot;, the content is executed after the existing 
     368unpack action.  If set to &quot;set&quot;, the contents are executed instead 
     369of the existing unpack action.  If set to &quot;unset&quot;, the unpack 
     370action is unset.  The default is &quot;set&quot;. 
     371</DL> 
     372<P> 
     373 
     374If the <I>&lt;source&gt;</I> element's &quot;use_objdir&quot; attribute is enabled and 
     375<B>mkencap</B>'s common source directory is set, the unpack action is 
     376executed in the common source directory.  Otherwise, the unpack action 
     377is executed in a subdirectory of the build tree that is named after the 
     378pkgspec of the profile. 
     379<P> 
     380By default, <B>mkencap</B> will unpack the source archive directly without 
     381using any commands specified in the profile.  If the <I>&lt;unpack&gt;</I> 
     382element is present, <B>mkencap</B> will execute the specified commands 
     383instead of unpacking the source archive directly. 
     384<P> 
     385See <B>COMMAND ELEMENTS</B> below for more information on how the 
     386<I>&lt;unpack&gt;</I> commands are executed. 
     387<A NAME="lbAO">&nbsp;</A> 
     388<H3>The &lt;patch&gt; Element</H3> 
     389 
     390Specifies a patch to be applied to the source files before building 
     391the package.  It may be specified zero or more times.  It supports the 
     392following attributes: 
     393<DL COMPACT> 
     394<DT><I>url</I> 
     395 
     396<DD> 
     397Optional.  A whitespace-delimited list of one or more URLs where the 
     398patch can be downloaded. 
     399<DT><I>options</I> 
     400 
     401<DD> 
     402Options to pass to the patch command.  Defaults to &quot;-p1&quot;. 
     403<DT><I>from_dir</I> 
     404 
     405<DD> 
     406Optional.  Subdirectory in which to execute the patch command. 
     407</DL> 
     408<P> 
     409 
     410The content of the <I>&lt;patch&gt;</I> element is the text of the patch file. 
     411It should be left empty if the &quot;url&quot; attribute is specified. 
     412<P> 
     413Example: 
     414<P> 
     415<DL COMPACT><DT><DD> 
     416<PRE> 
     417&lt;patch 
     418  url=&quot;<A HREF="ftp://ftp.feep.net/pub/software/authsrv/openssh-3.4p1-tis-auth.diff">ftp://ftp.feep.net/pub/software/authsrv/openssh-3.4p1-tis-auth.diff</A>&quot; 
     419/&gt; 
     420</PRE> 
     421 
     422</DL> 
     423 
     424<A NAME="lbAP">&nbsp;</A> 
     425<H3>The &lt;configure&gt; Element</H3> 
     426 
     427Specifies a set of shell commands to use to configure the source 
     428archives.  The following attributes are supported: 
     429<DL COMPACT> 
     430<DT><I>type<TT>&nbsp;&nbsp;&nbsp;&nbsp;</TT></I> 
     431 
     432<DD> 
     433Optional.  Specifies how the contents should be interpretted.  If set<BR> 
     434to &quot;prepend&quot;, the content is executed before the existing configuration 
     435action.  If set to &quot;append&quot;, the content is executed after the existing 
     436configuration action.  If set to &quot;set&quot;, the contents are executed instead 
     437of the existing configuration action.  If set to &quot;unset&quot;, the configure 
     438action is unset.  The default is &quot;set&quot;. 
     439</DL> 
     440<P> 
     441 
     442The configuration action is executed in the ${builddir} directory, which 
     443is created first if it doesn't exist.  The default configuration action 
     444is: 
     445<P> 
     446<DL COMPACT><DT><DD> 
     447<PRE> 
     448${srcdir}/configure \ 
     449      --prefix=&quot;${ENCAP_SOURCE}/${ENCAP_PKGNAME}&quot; \ 
     450      --sysconfdir=&quot;${ENCAP_TARGET}/etc&quot; 
     451</PRE> 
     452 
     453</DL> 
     454 
     455<P> 
     456Example: 
     457<P> 
     458<DL COMPACT><DT><DD> 
     459<PRE> 
     460&lt;configure&gt; 
     461   xmkmf 
     462   ${MAKE} includes 
     463&lt;/configure&gt; 
     464</PRE> 
     465 
     466</DL> 
     467 
     468<P> 
     469See <B>COMMAND ELEMENTS</B> below for more information on how the 
     470<I>&lt;configure&gt;</I> commands are executed. 
     471<A NAME="lbAQ">&nbsp;</A> 
     472<H3>The &lt;build&gt; Element</H3> 
     473 
     474Specifies a set of shell commands to use to build the source archives. 
     475The following attributes are supported: 
     476<DL COMPACT> 
     477<DT><I>type<TT>&nbsp;&nbsp;&nbsp;&nbsp;</TT></I> 
     478 
     479<DD> 
     480Optional.  Specifies how the contents should be interpretted.  If set<BR> 
     481to &quot;prepend&quot;, the content is executed before the existing build action. 
     482If set to &quot;append&quot;, the content is executed after the existing build 
     483action.  If set to &quot;set&quot;, the contents are executed instead of the 
     484existing build action.  If set to &quot;unset&quot;, the build action is unset. 
     485The default is &quot;set&quot;. 
     486</DL> 
     487<P> 
     488 
     489The build action is executed in the ${builddir} directory.  The default 
     490build action is: 
     491<P> 
     492<DL COMPACT><DT><DD> 
     493${MAKE} 
     494</DL> 
     495 
     496<P> 
     497Example: 
     498<P> 
     499<DL COMPACT><DT><DD> 
     500<PRE> 
     501&lt;build type=&quot;append&quot;&gt; 
     502   ${MAKE} certificate TYPE=dummy 
     503&lt;/build&gt; 
     504</PRE> 
     505 
     506</DL> 
     507 
     508<P> 
     509See <B>COMMAND ELEMENTS</B> below for more information on how the 
     510<I>&lt;build&gt;</I> commands are executed. 
     511<A NAME="lbAR">&nbsp;</A> 
     512<H3>The &lt;install&gt; Element</H3> 
     513 
     514The <I>&lt;install&gt;</I> element specifies how the <I>&lt;source&gt;</I> instance that 
     515contains it should be installed.  It supports the following attributes: 
     516<DL COMPACT> 
     517<DT><I>type</I> 
     518 
     519<DD> 
     520Optional.  Specifies how the contents should be interpretted.  If set to 
     521&quot;prepend&quot;, the content is executed before the existing installation action. 
     522If set to &quot;append&quot;, the content is executed after the existing installation 
     523action.  If set to &quot;set&quot;, the contents are executed instead of the existing 
     524installation action.  If set to &quot;unset&quot;, the install action is unset. 
     525The default is &quot;set&quot;. 
     526</DL> 
     527<P> 
     528 
     529The installation action is executed in the ${builddir} directory.  The 
     530default installation action is: 
     531<P> 
     532<DL COMPACT><DT><DD> 
     533<PRE> 
     534${MAKE} install sysconfdir=&quot;${ENCAP_SOURCE}/${ENCAP_PKGNAME}/etc&quot; 
     535</PRE> 
     536 
     537</DL> 
     538 
     539<P> 
     540Example: 
     541<P> 
     542<DL COMPACT><DT><DD> 
     543<PRE> 
     544&lt;install type=&quot;append&quot;&gt; 
     545   cp ssh_prng_cmds ${ENCAP_SOURCE}/${ENCAP_PKGNAME}/ssh_prng_cmds 
     546   cp moduli.out ${ENCAP_SOURCE}/${ENCAP_PKGNAME}/moduli 
     547&lt;/install&gt; 
     548</PRE> 
     549 
     550</DL> 
     551 
     552<P> 
     553See <B>COMMAND ELEMENTS</B> below for more information on how the 
     554<I>&lt;install&gt;</I> commands are executed. 
     555<A NAME="lbAS">&nbsp;</A> 
     556<H3>The &lt;clean&gt; Element</H3> 
     557 
     558The <I>&lt;clean&gt;</I> element specifies how the <I>&lt;source&gt;</I> instance that 
     559contains it should be cleaned up.  It supports the following attributes: 
     560<DL COMPACT> 
     561<DT><I>type</I> 
     562 
     563<DD> 
     564Optional.  Specifies how the contents should be interpretted.  If set 
     565to &quot;prepend&quot;, the content is executed before the existing clean action. 
     566If set to &quot;append&quot;, the content is executed after the existing clean 
     567action.  If set to &quot;set&quot;, the contents are executed instead of the 
     568existing clean action.  If set to &quot;unset&quot;, the clean action is unset. 
     569The default is &quot;set&quot;. 
     570</DL> 
     571<P> 
     572 
     573The clean action is executed in the ${builddir} directory.  The 
     574default clean action is: 
     575<P> 
     576<DL COMPACT><DT><DD> 
     577${MAKE} clean 
     578</DL> 
     579 
     580<P> 
     581Example: 
     582<P> 
     583<DL COMPACT><DT><DD> 
     584&lt;clean type=&quot;unset&quot; /&gt; 
     585</DL> 
     586 
     587<P> 
     588See <B>COMMAND ELEMENTS</B> below for more information on how the 
     589<I>&lt;clean&gt;</I> commands are executed. 
     590<A NAME="lbAT">&nbsp;</A> 
     591<H3>The &lt;prepackage&gt; Element</H3> 
     592 
     593The <I>&lt;prepackage&gt;</I> element specifies a set of commands to be executed 
     594after every <I>&lt;source&gt;</I> element has been built and installed but befor the 
     595package has been created.  It supports the following attributes: 
     596<DL COMPACT> 
     597<DT><I>type</I> 
     598 
     599<DD> 
     600Optional.  Specifies how the contents should be interpretted.  If set to 
     601&quot;prepend&quot;, the content is executed before the existing prepackage action. 
     602If set to &quot;append&quot;, the content is executed after the existing prepackage 
     603action.  If set to &quot;set&quot;, the contents are executed instead of the existing 
     604prepackage action.  If set to &quot;unset&quot;, the install action is unset. 
     605The default is &quot;set&quot;. 
     606</DL> 
     607<P> 
     608 
     609The prepackage action is executed in the &quot;${ENCAP_SOURCE}/${ENCAP_PKGNAME}&quot; 
     610directory.  The default prepackage action is: 
     611<P> 
     612<DL COMPACT><DT><DD> 
     613<PRE> 
     614find . -name lib -prune -o \ 
     615        \( -perm -0100 -o -perm -0010 -o -perm -0001 \) \ 
     616        -type f -print | xargs ${STRIP} 
     617</PRE> 
     618 
     619</DL> 
     620 
     621<P> 
     622Example: 
     623<P> 
     624<DL COMPACT><DT><DD> 
     625&lt;prepackage type=&quot;unset&quot; /&gt; 
     626</DL> 
     627 
     628<P> 
     629See <B>COMMAND ELEMENTS</B> below for more information on how the 
     630<I>&lt;prepackage&gt;</I> commands are executed. 
     631<A NAME="lbAU">&nbsp;</A> 
     632<H3>The &lt;include_file&gt; Element</H3> 
     633 
     634This element describes an additional file to add to the package.  The 
     635following attributes are supported: 
     636<DL COMPACT> 
     637<DT><I>name</I> 
     638 
     639<DD> 
     640Required.  The name of the file.  This must be a path name relative to 
     641the package directory. 
     642<DT><I>owner</I> 
     643 
     644<DD> 
     645Optional.  The owner of the installed file. 
     646<DT><I>group</I> 
     647 
     648<DD> 
     649Optional.  The group of the installed file. 
     650<DT><I>mode</I> 
     651 
     652<DD> 
     653Optional.  The mode of the installed file.  The default is 0644. 
     654</DL> 
     655<P> 
     656 
     657The content of the <I>&lt;include_file&gt;</I> element is the content of the file 
     658to install.  Note that a single leading newline will be stripped from 
     659the content to aid in readability. 
     660<P> 
     661Example: 
     662<P> 
     663<DL COMPACT><DT><DD> 
     664<PRE> 
     665&lt;include_file name=&quot;bin/webconf.in&quot; mode=&quot;0755&quot;&gt; 
     666   (...contents of file...) 
     667&lt;/include_file&gt; 
     668</PRE> 
     669 
     670</DL> 
     671 
     672<A NAME="lbAV">&nbsp;</A> 
     673<H3>The &lt;encapinfo&gt; Element</H3> 
     674 
     675This element contains the content of the encapinfo file to be created 
     676for the new package.  It supports no attributes. 
     677<P> 
     678Note that the following encapinfo fields should <B>not</B> be specified in an 
     679<I>&lt;encapinfo&gt;</I> element, since they will be determined dynamically by 
     680<B>mkencap</B>: 
     681<DL COMPACT> 
     682<DT>*<DD> 
     683<B>date</B> 
     684 
     685<DT>*<DD> 
     686<B>contact</B> 
     687 
     688<DT>*<DD> 
     689<B>platform</B> 
     690 
     691</DL> 
     692<P> 
     693 
     694Example: 
     695<P> 
     696<DL COMPACT><DT><DD> 
     697<PRE> 
     698&lt;encapinfo&gt; 
     699   exclude sbin/webconf.in 
     700&lt;/encapinfo&gt; 
     701</PRE> 
     702 
     703</DL> 
     704 
     705<A NAME="lbAW">&nbsp;</A> 
     706<H2>COMMAND ELEMENTS</H2> 
     707 
     708For those elements that contain commands to be executed by <B>mkencap</B>, 
     709the commands are parsed and executed the same way that they would be in 
     710a Makefile.  In particular, there are a few things to bear in mind. 
     711<P> 
     712First, each command is executed in its own subshell.  This means that 
     713process-specific actions like setting environment variables or changing 
     714directories will not propogate from one command to another.  For 
     715example, this element does not do what you might think: 
     716<P> 
     717<DL COMPACT><DT><DD> 
     718<PRE> 
     719&lt;!-- this will NOT work --&gt; 
     720&lt;configure&gt; 
     721  cd src 
     722  ./configure 
     723&lt;/configure&gt; 
     724</PRE> 
     725 
     726</DL> 
     727 
     728<P> 
     729Instead, you need to use something like this: 
     730<P> 
     731<DL COMPACT><DT><DD> 
     732<PRE> 
     733&lt;!-- this one will work --&gt; 
     734&lt;configure&gt;&lt;![CDATA[ 
     735  cd src &amp;&amp; ./configure 
     736]]&gt;&lt;/configure&gt; 
     737</PRE> 
     738 
     739</DL> 
     740 
     741<P> 
     742Generally, each line is interpretted as a single command.  If you need 
     743a single command to span multiple lines, you can use a backslash (&quot;\&quot;) 
     744to escape newlines.  For example: 
     745<P> 
     746<DL COMPACT><DT><DD> 
     747<PRE> 
     748&lt;configure&gt; 
     749${srcdir}/configure \ 
     750        --prefix=&quot;${ENCAP_SOURCE}/${ENCAP_PKGNAME}&quot; \ 
     751        --sysconfdir=&quot;${ENCAP_TARGET}/etc&quot; 
     752&lt;/configure&gt; 
     753</PRE> 
     754 
     755</DL> 
     756 
     757<P> 
     758Finally, <B>mkencap</B> will check the exit code of each command as it is 
     759executed.  If any command fails, the package creation process will abort 
     760immediately.  For example: 
     761<P> 
     762<DL COMPACT><DT><DD> 
     763<PRE> 
     764&lt;build&gt; 
     765${MAKE} 
     766${MAKE} test 
     767&lt;/build&gt; 
     768</PRE> 
     769 
     770</DL> 
     771 
     772<P> 
     773If the &quot;${MAKE}&quot; command fails, <B>mkencap</B> will terminate without 
     774executing &quot;${MAKE} test&quot;. 
     775<A NAME="lbAX">&nbsp;</A> 
     776<H2>PLATFORM CONDITIONALS</H2> 
     777 
     778In order to do conditional evaluation based on platform, the profile 
     779will be preprocessed with <B>m4</B>.  The following special <B>m4</B> 
     780macros have been written for this purpose: 
     781<DL COMPACT> 
     782<DT>*<DD> 
     783<B>PLATFORM_IF_EQUAL(</B><I>string</I><B>)</B> 
     784 
     785<DT>*<DD> 
     786<B>PLATFORM_IF_MATCH(</B><I>regex</I><B>)</B> 
     787 
     788<DT>*<DD> 
     789<B>PLATFORM_ELSE_IF_EQUAL(</B><I>string</I><B>)</B> 
     790 
     791<DT>*<DD> 
     792<B>PLATFORM_ELSE_IF_MATCH(</B><I>regex</I><B>)</B> 
     793 
     794<DT>*<DD> 
     795<B>PLATFORM_ELSE</B> 
     796 
     797<DT>*<DD> 
     798<B>PLATFORM_ENDIF</B> 
     799 
     800</DL> 
     801<P> 
     802 
     803The <B>*_MATCH</B> macros check the platform name against a regular 
     804expression.  The <B>*_EQUAL</B> macros check the platform name against 
     805a constant string. 
     806<P> 
     807Conditional blocks cannot be nested.  For example, this is illegal: 
     808<P> 
     809<DL COMPACT><DT><DD> 
     810<PRE> 
     811&lt;!-- This is illegal! --&gt; 
     812PLATFORM_IF_EQUAL(rs6000-aix4.3.3) 
     813   --with-rundir=/etc 
     814PLATFORM_ELSE 
     815   PLATFORM_IF_MATCH(.*linux) 
     816      --with-rundir=/var/state 
     817   PLATFORM_ELSE 
     818      --with-rundir=/var/run 
     819   PLATFORM_ENDIF 
     820PLATFORM_ENDIF 
     821</PRE> 
     822 
     823</DL> 
     824 
     825<P> 
     826Instead, use a conditional block with multuple options: 
     827<P> 
     828<DL COMPACT><DT><DD> 
     829<PRE> 
     830&lt;!-- This is the right way to do it. --&gt; 
     831PLATFORM_IF_EQUAL(rs6000-aix4.3.3) 
     832  --with-rundir=/etc 
     833PLATFORM_ELSE_IF_MATCH(.*linux) 
     834  --with-rundir=/var/state 
     835PLATFORM_ELSE 
     836  --with-rundir=/var/run 
     837PLATFORM_ENDIF 
     838</PRE> 
     839 
     840</DL> 
     841 
     842<P> 
     843Also, the normal <B>m4</B> quoting characters are &quot;`&quot; and &quot;'&quot;.  Since these are 
     844frequently used in shell scripts, <B>m4</B> will be configured to use the 
     845strings &quot;&lt;|&quot; and &quot;|&gt;&quot; as quote delimiters instead.  You will not normally 
     846need to use these delimiters, but if you run into a situation where <B>m4</B> 
     847is expanding something that you do not want it to, you can quote the 
     848text that you do not want expanded. 
     849<A NAME="lbAY">&nbsp;</A> 
     850<H3>ENVIRONMENT VARIABLES</H3> 
     851 
     852Because environment variable settings can affect the build process, 
     853<B>mkencap</B> will sanitize the environment in which the build commands 
     854are run. 
     855<P> 
     856First, <B>mkencap</B> will initialize the environment to the settings 
     857found in the <I>/usr/local/etc/mkencap_environment</I> file.  Next, 
     858<B>mkencap</B> will process any <I>&lt;environment&gt;</I> elements found in the 
     859package profile.  And finally, <B>mkencap</B> will set the following 
     860environment variables: 
     861<DL COMPACT> 
     862<DT><B>ENCAP_PKGNAME</B> 
     863 
     864<DD> 
     865The value of the <I>pkgspec</I> attribute of the <I>&lt;encap_profile&gt;</I> 
     866element. 
     867<DT><B>ENCAP_SOURCE</B> 
     868 
     869<DD> 
     870The Encap source directory. 
     871<DT><B>ENCAP_TARGET</B> 
     872 
     873<DD> 
     874The Encap target directory. 
     875<DT><B>MKENCAP_DOWNLOAD_DIR</B> 
     876 
     877<DD> 
     878The directory used by <B>mkencap</B> to store downloaded files. 
     879<DT><B>MKENCAP_SRC_TREE</B> 
     880 
     881<DD> 
     882The common source tree used by <B>mkencap</B>. 
     883<DT><B>MKENCAP_BUILD_TREE</B> 
     884 
     885<DD> 
     886The build tree used by <B>mkencap</B>. 
     887</DL> 
     888<P> 
     889 
     890In addition, the following variables will be set on a per-<I>&lt;source&gt;</I> 
     891basis: 
     892<DL COMPACT> 
     893<DT><B>srcdir</B> 
     894 
     895<DD> 
     896The full path to the unpacked sources, based on the <I>subdir</I> and 
     897<I>use_objdir</I> attributes for the <I>&lt;source&gt;</I> and the number of 
     898sources in the package. 
     899<DT><B>builddir</B> 
     900 
     901<DD> 
     902The full path to the build directory, based on the <I>subdir</I> attribute 
     903for the <I>&lt;source&gt;</I> and the number of sources in the package. 
     904</DL> 
     905<P> 
     906 
     907All of these environment variables are available for use in shell 
     908commands. 
     909<A NAME="lbAZ">&nbsp;</A> 
     910<H2>SEE ALSO</H2> 
     911 
     912<B><A HREF="/projects/bcfg2/wiki/EncapManMkencap">mkencap</A></B>(1), 
     913 
     914<B><A HREF="http://www.gnu.org/software/m4/">m4</A></B>(1) 
     915</BODY> 
     916}}}