DragonFly On-Line Manual Pages
encap_profile(5) Package Management encap_profile(5)
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 "<" and ">" 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., "]]>").
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:
o <unpack>
o <patch>
o <configure>
o <build>
o <install>
o <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:
o date
o contact
o 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:
o PLATFORM_IF_EQUAL(string)
o PLATFORM_IF_MATCH(regex)
o PLATFORM_ELSE_IF_EQUAL(string)
o PLATFORM_ELSE_IF_MATCH(regex)
o PLATFORM_ELSE
o 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)
University of Illinois Oct 2002 encap_profile(5)