| Skip Navigation Links | |
| Exit Print View | |
|
man pages section 1: User Commands Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
man pages section 1: User Commands Oracle Solaris 11.1 Information Library |
- Image Packaging System manifest transmogrifier
/usr/bin/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.
pkgmogrify provides the following:
Macro replacement to facilitate sharing of a single manifest across various architectures and platforms.
Inclusion of other manifests or manifest fragments such as standard components and transforms.
Transformation of package actions, including the modification, deletion, or addition of action attributes.
The following options are supported:
Display a usage message.
Define macro as a macro, with the value value. Macros appear in the input file as $(macro). Substitution is repeated until no more translations are found. Common idioms include:
Elimination of lines in a manifest on other architectures by using an architecture-specific tag at the beginning of the line:
$(sparc_ONLY)file ...
When 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.
Specifying platform-specific portions of path names, such as the name of the 64-bit architecture directory for executables and libraries:
file NOHASH path=usr/bin/$(ARCH64)/cputrack ...
These macros should be set to the desired value on the command line. There are no predefined macro values.
Add the specified directory to the search path for both files specified on the command line and embedded include directives.
Write manifest output to the specified file. The file is not written if an error occurs or if a transform directive causes an abort operation. By default, manifest output is written to stdout.
Write output resulting from transform directive print operations to the specified file. The file is not written if an error occurs or if a transform directive causes an abort operation. By default, print output is written to stdout.
Ignore include directives in files. Only files specified on the command line (or stdin) are processed.
Write comments into the output manifest showing the effect of transforms. This information can aid in debugging.
Two 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:
[action-name ... ] [attribute=<value-regexp> ...]
At least one specified action-name must match. Every specified attribute must match. Action names and attributes are listed in “Actions” in the pkg(5) man page. The regular expression syntax used is that of Python. For more information about Python regular expression syntax, use the command pydoc re or see more complete 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:
Add a value to an attribute. This operation takes two arguments. The first argument is the name of the attribute, and the second is the value.
Set the value of an attribute if it doesn't already exist. This operation takes the same two arguments as the add operation.
Remove attribute values. This operation takes two arguments. The first argument is the name of the attribute. The second argument is a regular expression to match the attribute values deleted. Unlike the regular expression used to match an action, this expression is unanchored.
Discards this action.
Modifies an attribute of the action. This operation takes three arguments. The first argument is the name of the attribute, and the second is a regular expression matching the attribute value. The third argument is the replacement string substituted for the portion of the value matched by the regular expression. Unlike the regular expression used to match an action, this expression is unanchored. Normal regular expression backreferences, of the form \1, \2, and so on, are available in the replacement string if groups are defined in the regular expression.
Emit a line to the manifest output stream. This must be a valid action string, empty (resulting in a blank line), or a comment (a # followed by arbitrary text).
Terminate manifest processing. No manifest is output and no print 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 a message to the output file specified with -P.
Set the value of an attribute. This operation takes the same two arguments as the add 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.filename refers to the name of the file in which the action was found.
pkg.manifest.lineno refers to the line on which the action was found.
Three synthetic attributes are similar to ones used in pkg:
action.hash refers to the hash value of the action if the action carries a payload. For actions with payloads, the set operation can change the hash of the action by operating on the action.hash attribute.
action.key refers to the value of the key attribute.
action.name refers to the name of the action.
If 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 behavior. 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.
It 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:
Lines are read from input files.
Macros are applied.
<include ...> and <transform> directives are processed, causing additional files to be found and read.
Once all input has been accumulated, each line in the input is converted into actions and all transforms applied.
Once processing is complete and successful, the output is written.
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 following exit values are returned:
Everything worked.
Something bad but anticipated happened.
Invalid command line options were specified.
Unexpected processing error.
This directory contains files with useful transforms to set facets, actuators, and other attributes.
See attributes(5) for descriptions of the following attributes:
|
http://hub.opensolaris.org/bin/view/Project+pkg/
|