| PKGMOGRIFY(1) | User Commands | PKGMOGRIFY(1) |
pkgmogrify — Image
Packaging System manifest transmogrifier
pkgmogrify |
[-vi] [-I
includedir]... [-D
macro=value]...
[-O outputfile]
[-P printfile]
[inputfile]... |
pkgmogrify provides for programmatic
editing of package manifests to simplify the typical transformations needed
when automating software builds and package publication. It reads all of the
input file(s) in the order specified and then will apply any embedded
directives found within as detailed in the Embedded Directives; section
below. If no files are named, input will be read from
stdin. ‘-’ can also be specified as a
filename to use stdin as input, alone, or in
combination with other files.
pkgmogrify provides the following:
The following options are supported:
--help,
-?-D
macro=valueWhen processing the SPARC architecture, this macro would be set to the empty string. When processing other architectures, this macro would be set to # on the command line, thus eliminating this action from the manifest on the current architecture.
These macros should be set to the desired value on the command line. There are no predefined macro values.
-I
includedir-O
outputfilestdout.-P
printfilestdout.-istdin) are processed .-vTwo types of directives are supported in manifest files: include directives and transform directives.
Include directives are of the form:
<include
file>This directive causes pkgmogrify to search
for a file named file first in the current directory
and then in the directories specified with the -I
option. If found, the contents of the file are inserted into the manifest at
the point at which the directive is encountered. If not found,
pkgmogrify exits with an error.
Transform directives are of the form:
<transform
matching-criteria ->
operation>These directives are accumulated until all inputs have been read into memory, and then applied to the actions in the order in which they were encountered.
Matching criteria are of the form:
At least one specified action-name must match. Every specified attribute must match. Action names and attributes are listed in "Actions" in the pkg(7) man page. The regular expression syntax used is that of Python. For more information about Python regular expression syntax, see the documentation at http://docs.python.org/dev/howto/regex.html. The regular expression is anchored at the beginning but not at the end. Therefore, a regular expression matching files by their extensions must include a leading ‘.*’ and should include a trailing ‘$’.
Multiple criteria can be specified, separated by spaces.
The following operations are available:
adddefaultadd
operation.deletedropeditemitexitprint operations are applied. If one argument is
given, it must be an integer, and it is used as the exit code. The default
is 0. If two arguments are given, the first is the exit code, and the
second is a message to be printed to stderr.print-P.setadd operation.All operations except for delete and
drop take (possibly optional) arguments whose
contents go to the output stream. These strings can contain three different
kinds of special tokens which allow the output to contain information that
is not based on a fixed transformation of each action.
The first kind of substitution allows the operation
to refer to the values of attributes of the current action by putting the
name of the attribute inside parentheses following a percent sign. For
example,
%(alias) refers
to the value of the action's alias attribute.
Several synthetic attributes exist. Two are unique to
pkgmogrify:
pkg.manifest.filenamepkg.manifest.linenoThree synthetic attributes are similar to ones used in pkg(1):
action.hashset operation can change the
hash of the action by operating on the action.hash
attribute.action.keyaction.nameIf the attribute whose value is requested does not exist,
pkgmogrify exits with an error. To prevent exiting
with an error, follow the attribute name with
;notfound= and a value to substitute in place of the
attribute value. For example,
%(alias;notfound='no alias')
prints the value of the attribute alias if it
exists, and prints no
alias otherwise.
If the attribute whose value is requested is multi-valued, each
value is printed, separated by spaces. Similarly to the
notfound token, the tokens
prefix, suffix, and
sep can be used to change this behaviour. The string
denoted by prefix is prepended to each value, the
string denoted by suffix is appended to each value,
and sep is placed in between the suffix of one value
and the prefix of the next.
Similarly to action attributes,
pkgmogrify directives can reference package
attributes using braces instead of parentheses:
%{pkg.fmri}.
At the point at which the transform directive is applied, the attribute must
have been defined in a set action, or it is treated
as
notfound,
described above. When the processing reaches the end of the manifest file
describing the package, the attributes are cleared for the next package. The
following synthetic attributes are also automatically generated from
pkg.fmri when it is encountered:
pkg.fmri.nameIt is useful not only to reference package attributes as if they
were action attributes, but also to match on them, and even temporarily
modify them. Therefore a synthetic action name, pkg, is
available (only in the context of pkgmogrify) for
use in these situations.
When pkgmogrify finishes reading a
manifest specified on the command line and that manifest defined a
pkg.fmri package attribute,
pkgmogrify creates this synthetic
pkg action, whose attributes are the package's attributes.
A <transform> directive can then match on this
action, just as it can match on any other action.
Operations on a pkg action are special in that
they take place only in memory and do not directly affect the emitted
manifest. For instance, trying to set an attribute on a
pkg action via the add,
default, or set operations
does not result in a set action being added to the
manifest, though it will be available for other
<transform> directives to match on. Attempting
to emit a pkg action causes
an error. To add a package attribute, emit a
set action instead.
The third kind of substitution is a backreference. This
substitution is not like the ones usable in the edit
operation, but is a reference to groups listed in the transformation match
on the left-hand side of the ->. These are
indicated by
%<1>,
%<2>,
and so on, in the order seen in the matching criteria.
The order of processing is as follows:
<include
...> and <transform>
directives are processed, causing additional files to be found and
read.The following exit values are returned:
Example 1 Add Tags To SMF Manifests
Add tags to Service Management Facility (SMF) manifests so they get imported when the package is installed on a live system.
<transform file path=(var|lib)/svc/manifest/.*\.xml -> \
add restart_fmri svc:/system/manifest-import:default>
Example 2 Move Files
Move files from usr/sfw/bin to usr/bin.
<transform file -> edit path usr/sfw/bin usr/bin>
Example 3 Specify Reboot Needed
Add reboot-needed tags to files under
/kernel that are not ‘.conf’ files.
Note that this example leverages how transforms are applied to each action
in the order seen in the input files.
<transform file path=kernel/.* -> set reboot-needed true> <transform file path=kernel/.*\.conf -> delete reboot-needed .*>
This can also be done in a single transform rule with regular expressions.
Example 4 Convert FMRI Attribute To Depend Action
Convert the package attribute pkg.fmri
into a depend action to become part of an
incorporation.
<transform set name=pkg.fmri -> \
emit depend type=incorporate fmri=%(value)>
<transform set name=pkg.fmri -> drop>
Example 5 Print a List of Bug Numbers
Print a comma-separated list of quoted and prefixed bug numbers.
set name=bugs value=12345 value=54321 value=13579 value=97531
<transform set name=bugs -> \
print %(value;sep=",";prefix="bug='";suffix="'")>
Example 6 Allow For Missing Attributes
Safely print a message even when an attribute is missing.
<transform driver -> print Found aliases: %(alias;notfound=<none>)>
Example 7 Set Default Values
Set default owner, group, and permission values.
<transform file dir -> default owner root> <transform file dir -> default group bin> <transform file -> default mode 0444> <transform dir -> default mode 0755>
Example 8 Add Dependencies To Packages That Are Not Marked Obsolete
For any package that is not marked obsolete, add a dependency on the incorporation for the consolidation that delivers the package. This set of transforms must occur after the manifest has been read in, or the dependency will always be emitted. Because modifying a pkg action has no permanent effect, there is no need to clean up attributes matching pkg.obsolete=false.
<transform pkg -> default pkg.obsolete false>
<transform pkg pkg.obsolete=false -> emit depend \
fmri=consolidation/$(CONS)/$(CONS)--incorporation type=require>
Example 9 Exit and Print a Message When an Error Is Found
Error out with a message when an obsolete attribute is found in a manifest.
<transform file dir link hardlink opensolaris.zone=.* -> \
exit 1 The opensolaris.zone attribute is obsolete.>
Example 10 Set the Appropriate Locale Facet
Set the locale facet appropriate for the path name under consideration.
<transform dir file link hardlink path=.*/locale/([^/]+).* -> \
default facet.locale.%<1> true>
The command line interface of pkgmogrify
is
Uncommitted.
The output of pkgmogrify is
Not-An-Interface
and may change at any time.
| October 1, 2024 | OmniOS |