NAME

encap_profile - Encap package creation information  

VERSION

This man page documents version 1.0 of the Encap profile format.  

DESCRIPTION

Encap profiles contain all the information needed to build an Encap package. The profile is an XML document.  

THE BASICS OF XML

As with any XML document, the first line of the profile must be:

<?xml version="1.0"?>

An XML element with content looks like this:

<element attribute="value" ...>
  content
</element>

An empty element looks like this:

<element attribute="value" ... />

Element names are case-sensitive.

The "<" and ">" characters need to be replaced with predefined entity tags "&lt;" and "&gt;" when they're not part of an element tag, just like in HTML. However, for whole blocks of text that may contain these special characters, you can enclose them like this:

<![CDATA[
   echo foo > output
]]>

If for some reason you need to include the "]]>" string within a CDATA section, you can replace the ">" with its entity tag, just like you'd do outside of a CDATA section (i.e., "]]&gt;").

The XML comment delimiters are "<!--" and "-->".  

PROFILE STRUCTURE

Here's a high-level summary of the hierarchical relationship of the elements described below:

<encap_profile>
   <notes>
   <ChangeLog>
      <change>
   <prereq>
   <environment>
   <prepare>
   <source>
      <unpack>
      <patch>
      <configure>
      <build>
      <install>
      <clean>
   <prepackage>
   <include_file>
   <encapinfo>

 

The <encap_profile> Element

The <encap_profile> element is the root XML element of the package profile. All other elements must be contained within the <encap_profile> element.

The <encap_profile> element supports the following attributes:

profile_ver

Indicates what version of the Encap Profile format is being used. This attribute is mandatory and must have the value "1.0".

pkgspec

Sets the full name of the package to be created. This attribute is mandatory.

Example:

<encap_profile profile_ver="1.0" pkgspec="foo-1.0+1">
   ...
</encap_profile>

 

The <notes> Element

This optional element may contain arbitrary text. It is intended to store README-style notes.

Example:

<notes>
  These are human-readable notes about a profile.
</notes>

 

The <ChangeLog> and <change> Elements

The <ChangeLog> element is composed of one or more <change> elements that document changes to the profile. The <ChangeLog> element itself supports no attributes.

The <change> element supports the following attributes:

date

Optional. Indicates the date of the ChangeLog entry.

version

Required. Indicates the version of the package to which the ChangeLog entry applies.

Example:

<ChangeLog>
  <change version="1.0+1">
    Fixed a bug in the postinstall script from version 1.0.
  </change>
  <change version="1.0">
    Initial release.
  </change>
</ChangeLog>

 

The <prereq> Element

The <prereq> element specifies a build-time prerequisite package. It may be specified zero or more times, but must be empty. It supports the following attributes:

package

Required. Specifies the pkgspec of the required package.

use_bin

Optional. If set to "yes", prepends package's bin subdirectory to the PATH environment variable.

use_lib

Optional. If set to "yes", adds package's include and lib subdirectories to the CPPFLAGS and LDFLAGS environment variables.

Example:

<prereq package="bar-2.5.1" />

 

The <environment> Element

Specifies an environment setting. It may be specified zero or more times, but must be empty. It supports the following attributes:

variable

Required. The name of the environment variable.

value

Optional. The new value for the variable.

type    

Optional. Specifies how the value should be interpretted. If set
to "prepend", the value is prepended to the existing value. If set to "append", the content is appended to the existing value. If set to "set", the value completely replaces the existing value. If set to "unset", the variable is unset. The default is "set".

Example:

<environment
        variable="PATH"
        value=":/usr/local/bin"
        type="append"
/>

See the ENVIRONMENT VARIABLES section below for more information on how environment variables are set and used.  

The <prepare> Element

The <prepare> element specifies a set of commands to be executed before any <source> elements are processed. It supports the following attributes:

type

Optional. Specifies how the contents should be interpretted. If set to "prepend", the content is executed before the existing prepare action. If set to "append", the content is executed after the existing prepare action. If set to "set", the contents are executed instead of the existing prepare action. If set to "unset", the prepare action is unset. The default is "set".

The prepare action is executed in whatever directory mkencap was invoked in. By default, no prepare commands are executed.

See COMMAND ELEMENTS below for more information on how the <prepare> commands are executed.  

The <source> Element

Specifies a source (which in this context means "anything you need to download to build the package"). It may be specified multiple times, but must be specified at least once. It supports the following attributes:

url

Required. A whitespace-delimited list of one or more URLs where the source can be downloaded.

Note that the basename of each URL in the list must be the same. No checking is done to ensure that they do not differ, but the results are undefined if they are not identical.

subdir

Optional. The name of the subdirectory into which the source files will be unpacked (if different from the name of the source archive).

create_subdir

If set to "yes", the subdirectory specified by the "subdir" attribute is created and cd'd to before running the unpack action (see below). The default is "no".

build_subdir

Optional. If set, it denotes a relative path from the source directory where the configure, build, install, and clean actions are invoked.

use_objdir

Set to "yes" or "no" to indicate whether software can be built in an objdir. Defaults to "yes".

The <source> element contains zero or more of the following elements, which are described below:

*

<unpack>

*

<patch>

*

<configure>

*

<build>

*

<install>

*

<clean>

Example:

<source
   url="ftp://ftp.isc.org/isc/bind-8.3.3/bind-src.tar.gz"
   subdir="bind-8.3.3"
   use_objdir="no"
/>

 

The <unpack> Element

Specifies a set of shell commands to use to unpack the source archives. The following attributes are supported:

type

Optional. Specifies how the contents should be interpretted. If set to "prepend", the content is executed before the existing unpack action. If set to "append", the content is executed after the existing unpack action. If set to "set", the contents are executed instead of the existing unpack action. If set to "unset", the unpack action is unset. The default is "set".

If the <source> element's "use_objdir" attribute is enabled and mkencap's common source directory is set, the unpack action is executed in the common source directory. Otherwise, the unpack action is executed in a subdirectory of the build tree that is named after the pkgspec of the profile.

By default, mkencap will unpack the source archive directly without using any commands specified in the profile. If the <unpack> element is present, mkencap will execute the specified commands instead of unpacking the source archive directly.

See COMMAND ELEMENTS below for more information on how the <unpack> commands are executed.  

The <patch> Element

Specifies a patch to be applied to the source files before building the package. It may be specified zero or more times. It supports the following attributes:

url

Optional. A whitespace-delimited list of one or more URLs where the patch can be downloaded.

options

Options to pass to the patch command. Defaults to "-p1".

from_dir

Optional. Subdirectory in which to execute the patch command.

The content of the <patch> element is the text of the patch file. It should be left empty if the "url" attribute is specified.

Example:

<patch
  url="ftp://ftp.feep.net/pub/software/authsrv/openssh-3.4p1-tis-auth.diff"
/>

 

The <configure> Element

Specifies a set of shell commands to use to configure the source archives. The following attributes are supported:

type    

Optional. Specifies how the contents should be interpretted. If set
to "prepend", the content is executed before the existing configuration action. If set to "append", the content is executed after the existing configuration action. If set to "set", the contents are executed instead of the existing configuration action. If set to "unset", the configure action is unset. The default is "set".

The configuration action is executed in the ${builddir} directory, which is created first if it doesn't exist. The default configuration action is:

${srcdir}/configure \
      --prefix="${ENCAP_SOURCE}/${ENCAP_PKGNAME}" \
      --sysconfdir="${ENCAP_TARGET}/etc"

Example:

<configure>
   xmkmf
   ${MAKE} includes
</configure>

See COMMAND ELEMENTS below for more information on how the <configure> commands are executed.  

The <build> Element

Specifies a set of shell commands to use to build the source archives. The following attributes are supported:

type    

Optional. Specifies how the contents should be interpretted. If set
to "prepend", the content is executed before the existing build action. If set to "append", the content is executed after the existing build action. If set to "set", the contents are executed instead of the existing build action. If set to "unset", the build action is unset. The default is "set".

The build action is executed in the ${builddir} directory. The default build action is:

${MAKE}

Example:

<build type="append">
   ${MAKE} certificate TYPE=dummy
</build>

See COMMAND ELEMENTS below for more information on how the <build> commands are executed.  

The <install> Element

The <install> element specifies how the <source> instance that contains it should be installed. It supports the following attributes:

type

Optional. Specifies how the contents should be interpretted. If set to "prepend", the content is executed before the existing installation action. If set to "append", the content is executed after the existing installation action. If set to "set", the contents are executed instead of the existing installation action. If set to "unset", the install action is unset. The default is "set".

The installation action is executed in the ${builddir} directory. The default installation action is:

${MAKE} install sysconfdir="${ENCAP_SOURCE}/${ENCAP_PKGNAME}/etc"

Example:

<install type="append">
   cp ssh_prng_cmds ${ENCAP_SOURCE}/${ENCAP_PKGNAME}/ssh_prng_cmds
   cp moduli.out ${ENCAP_SOURCE}/${ENCAP_PKGNAME}/moduli
</install>

See COMMAND ELEMENTS below for more information on how the <install> commands are executed.  

The <clean> Element

The <clean> element specifies how the <source> instance that contains it should be cleaned up. It supports the following attributes:

type

Optional. Specifies how the contents should be interpretted. If set to "prepend", the content is executed before the existing clean action. If set to "append", the content is executed after the existing clean action. If set to "set", the contents are executed instead of the existing clean action. If set to "unset", the clean action is unset. The default is "set".

The clean action is executed in the ${builddir} directory. The default clean action is:

${MAKE} clean

Example:

<clean type="unset" />

See COMMAND ELEMENTS below for more information on how the <clean> commands are executed.  

The <prepackage> Element

The <prepackage> element specifies a set of commands to be executed after every <source> element has been built and installed but befor the package has been created. It supports the following attributes:

type

Optional. Specifies how the contents should be interpretted. If set to "prepend", the content is executed before the existing prepackage action. If set to "append", the content is executed after the existing prepackage action. If set to "set", the contents are executed instead of the existing prepackage action. If set to "unset", the install action is unset. The default is "set".

The prepackage action is executed in the "${ENCAP_SOURCE}/${ENCAP_PKGNAME}" directory. The default prepackage action is:

find . -name lib -prune -o \
        \( -perm -0100 -o -perm -0010 -o -perm -0001 \) \
        -type f -print | xargs ${STRIP}

Example:

<prepackage type="unset" />

See COMMAND ELEMENTS below for more information on how the <prepackage> commands are executed.  

The <include_file> Element

This element describes an additional file to add to the package. The following attributes are supported:

name

Required. The name of the file. This must be a path name relative to the package directory.

owner

Optional. The owner of the installed file.

group

Optional. The group of the installed file.

mode

Optional. The mode of the installed file. The default is 0644.

The content of the <include_file> element is the content of the file to install. Note that a single leading newline will be stripped from the content to aid in readability.

Example:

<include_file name="bin/webconf.in" mode="0755">
   (...contents of file...)
</include_file>

 

The <encapinfo> Element

This element contains the content of the encapinfo file to be created for the new package. It supports no attributes.

Note that the following encapinfo fields should not be specified in an <encapinfo> element, since they will be determined dynamically by mkencap:

*

date

*

contact

*

platform

Example:

<encapinfo>
   exclude sbin/webconf.in
</encapinfo>

 

COMMAND ELEMENTS

For those elements that contain commands to be executed by mkencap, the commands are parsed and executed the same way that they would be in a Makefile. In particular, there are a few things to bear in mind.

First, each command is executed in its own subshell. This means that process-specific actions like setting environment variables or changing directories will not propogate from one command to another. For example, this element does not do what you might think:

<!-- this will NOT work -->
<configure>
  cd src
  ./configure
</configure>

Instead, you need to use something like this:

<!-- this one will work -->
<configure><![CDATA[
  cd src && ./configure
]]></configure>

Generally, each line is interpretted as a single command. If you need a single command to span multiple lines, you can use a backslash ("\") to escape newlines. For example:

<configure>
${srcdir}/configure \
        --prefix="${ENCAP_SOURCE}/${ENCAP_PKGNAME}" \
        --sysconfdir="${ENCAP_TARGET}/etc"
</configure>

Finally, mkencap will check the exit code of each command as it is executed. If any command fails, the package creation process will abort immediately. For example:

<build>
${MAKE}
${MAKE} test
</build>

If the "${MAKE}" command fails, mkencap will terminate without executing "${MAKE} test".  

PLATFORM CONDITIONALS

In order to do conditional evaluation based on platform, the profile will be preprocessed with m4. The following special m4 macros have been written for this purpose:

*

PLATFORM_IF_EQUAL(string)

*

PLATFORM_IF_MATCH(regex)

*

PLATFORM_ELSE_IF_EQUAL(string)

*

PLATFORM_ELSE_IF_MATCH(regex)

*

PLATFORM_ELSE

*

PLATFORM_ENDIF

The *_MATCH macros check the platform name against a regular expression. The *_EQUAL macros check the platform name against a constant string.

Conditional blocks cannot be nested. For example, this is illegal:

<!-- This is illegal! -->
PLATFORM_IF_EQUAL(rs6000-aix4.3.3)
   --with-rundir=/etc
PLATFORM_ELSE
   PLATFORM_IF_MATCH(.*linux)
      --with-rundir=/var/state
   PLATFORM_ELSE
      --with-rundir=/var/run
   PLATFORM_ENDIF
PLATFORM_ENDIF

Instead, use a conditional block with multuple options:

<!-- This is the right way to do it. -->
PLATFORM_IF_EQUAL(rs6000-aix4.3.3)
  --with-rundir=/etc
PLATFORM_ELSE_IF_MATCH(.*linux)
  --with-rundir=/var/state
PLATFORM_ELSE
  --with-rundir=/var/run
PLATFORM_ENDIF

Also, the normal m4 quoting characters are "`" and "'". Since these are frequently used in shell scripts, m4 will be configured to use the strings "<|" and "|>" as quote delimiters instead. You will not normally need to use these delimiters, but if you run into a situation where m4 is expanding something that you do not want it to, you can quote the text that you do not want expanded.  

ENVIRONMENT VARIABLES

Because environment variable settings can affect the build process, mkencap will sanitize the environment in which the build commands are run.

First, mkencap will initialize the environment to the settings found in the /usr/local/etc/mkencap_environment file. Next, mkencap will process any <environment> elements found in the package profile. And finally, mkencap will set the following environment variables:

ENCAP_PKGNAME

The value of the pkgspec attribute of the <encap_profile> element.

ENCAP_SOURCE

The Encap source directory.

ENCAP_TARGET

The Encap target directory.

MKENCAP_DOWNLOAD_DIR

The directory used by mkencap to store downloaded files.

MKENCAP_SRC_TREE

The common source tree used by mkencap.

MKENCAP_BUILD_TREE

The build tree used by mkencap.

In addition, the following variables will be set on a per-<source> basis:

srcdir

The full path to the unpacked sources, based on the subdir and use_objdir attributes for the <source> and the number of sources in the package.

builddir

The full path to the build directory, based on the subdir attribute for the <source> and the number of sources in the package.

All of these environment variables are available for use in shell commands.  

SEE ALSO

mkencap(1), m4(1)