'\" te .\" Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. .TH pkgmogrify 1 "12 Jul 2013" "SunOS 5.11" "User Commands" .SH NAME pkgmogrify \- Image Packaging System manifest transmogrifier .SH SYNOPSIS .LP .nf /usr/bin/pkgmogrify [-vi] [-I \fIincludedir\fR]\&.\&.\&. [-D \fImacro\fR=\fIvalue\fR]\&.\&.\&. [-O \fIoutputfile\fR] [-P \fIprintfile\fR] [\fIinputfile\fR \&.\&.\&.] .fi .SH DESCRIPTION .sp .LP \fBpkgmogrify\fR provides for programmatic editing of package manifests to simplify the typical transformations needed when automating software builds and package publication\&. .sp .LP \fBpkgmogrify\fR provides the following: .RS +4 .TP .ie t \(bu .el o Macro replacement to facilitate sharing of a single manifest across various architectures and platforms\&. .RE .RS +4 .TP .ie t \(bu .el o Inclusion of other manifests or manifest fragments such as standard components and transforms\&. .RE .RS +4 .TP .ie t \(bu .el o Transformation of package actions, including the modification, deletion, or addition of action attributes\&. .RE .SH OPTIONS .sp .LP The following options are supported: .sp .ne 2 .mk .na \fB\fB-?\fR\fR .ad .br .na \fB\fB--help\fR\fR .ad .br .sp .6 .RS 4n Display a usage message\&. .RE .sp .ne 2 .mk .na \fB\fB-D\fR \fImacro\fR=\fIvalue\fR\fR .ad .br .sp .6 .RS 4n Define \fImacro\fR as a macro, with the value \fIvalue\fR\&. This option can be specified multiple times\&. Macros appear in the input file as \fB$(macro)\fR\&. Substitution is repeated until no more translations are found\&. Common idioms include: .RS +4 .TP .ie t \(bu .el o Elimination of lines in a manifest on other architectures by using an architecture-specific tag at the beginning of the line: .sp .sp .in +2 .nf $(sparc_ONLY)file \&.\&.\&. .fi .in -2 .sp When processing the SPARC architecture, this macro would be set to the empty string\&. When processing other architectures, this macro would be set to \fB#\fR on the command line, thus eliminating this action from the manifest on the current architecture\&. .RE .RS +4 .TP .ie t \(bu .el o Specifying platform-specific portions of path names, such as the name of the 64-bit architecture directory for executables and libraries: .sp .sp .in +2 .nf file path=usr/bin/$(ARCH64)/cputrack \&.\&.\&. .fi .in -2 .sp These macros should be set to the desired value on the command line\&. There are no predefined macro values\&. .RE .RE .sp .ne 2 .mk .na \fB\fB-I\fR \fIincludedir\fR\fR .ad .br .sp .6 .RS 4n Add the specified directory to the search path, both for files specified on the command line and for embedded include directives\&. This option can be specified multiple times\&. .RE .sp .ne 2 .mk .na \fB\fB-O\fR \fIoutputfile\fR\fR .ad .br .sp .6 .RS 4n 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 \fBstdout\fR\&. .RE .sp .ne 2 .mk .na \fB\fB-P\fR \fIprintfile\fR\fR .ad .br .sp .6 .RS 4n 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 \fBstdout\fR\&. .RE .sp .ne 2 .mk .na \fB\fB-i\fR\fR .ad .br .sp .6 .RS 4n Ignore include directives in files\&. Only files specified on the command line (or \fBstdin\fR) are processed\&. .RE .sp .ne 2 .mk .na \fB\fB-v\fR\fR .ad .br .sp .6 .RS 4n Write comments into the output manifest showing the effect of transforms\&. This information can aid in debugging\&. .RE .SH EMBEDDED DIRECTIVES .sp .LP Two types of directives are supported in manifest files: include directives and transform directives\&. .sp .LP Include directives are of the form: .sp .in +2 .nf .fi .in -2 .sp .sp .LP This directive causes \fBpkgmogrify\fR to search for a file named \fBfile\fR first in the current directory and then in the directories specified with the \fB-I\fR 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, \fBpkgmogrify\fR exits with an error\&. .sp .LP Transform directives are of the form: .sp .in +2 .nf \fIoperation\fR> .fi .in -2 .sp .sp .LP 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\&. .sp .LP Matching criteria are of the form: .sp .in +2 .nf [\fIaction-name\fR \&.\&.\&. ] [\fIattribute\fR=<\fIvalue-regexp\fR> \&.\&.\&.] .fi .in -2 .sp .sp .LP At least one specified \fIaction-name\fR must match\&. Every specified \fIattribute\fR must match\&. Action names and attributes are listed in "Actions" in the \fBpkg\fR(5) man page\&. The regular expression syntax used is that of Python\&. For more information about Python regular expression syntax, use the command \fBpydoc re\fR or see more complete documentation at \fBhttp://docs\&.python\&.org/dev/howto/regex\&.html\fR\&. 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 \fB\&.*\fR and should include a trailing \fB$\fR\&. .sp .LP Multiple criteria can be specified, separated by spaces\&. .sp .LP The following operations are available: .sp .ne 2 .mk .na \fB\fBadd\fR\fR .ad .RS 11n .rt 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\&. .RE .sp .ne 2 .mk .na \fB\fBdefault\fR\fR .ad .RS 11n .rt Set the value of an attribute if it doesn\'t already exist\&. This operation takes the same two arguments as the \fBadd\fR operation\&. .RE .sp .ne 2 .mk .na \fB\fBdelete\fR\fR .ad .RS 11n .rt 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\&. .RE .sp .ne 2 .mk .na \fB\fBdrop\fR\fR .ad .RS 11n .rt Discards this action\&. .RE .sp .ne 2 .mk .na \fB\fBedit\fR\fR .ad .RS 11n .rt 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 \fB\e1\fR, \fB\e2\fR, and so on, are available in the replacement string if groups are defined in the regular expression\&. .RE .sp .ne 2 .mk .na \fB\fBemit\fR\fR .ad .RS 11n .rt 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 \fB#\fR followed by arbitrary text)\&. .RE .sp .ne 2 .mk .na \fB\fBexit\fR\fR .ad .RS 11n .rt Terminate manifest processing\&. No manifest is output and no \fBprint\fR 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 \fBstderr\fR\&. .RE .sp .ne 2 .mk .na \fB\fBprint\fR\fR .ad .RS 11n .rt Print a message to the output file specified with \fB-P\fR\&. .RE .sp .ne 2 .mk .na \fB\fBset\fR\fR .ad .RS 11n .rt Set the value of an attribute\&. This operation takes the same two arguments as the \fBadd\fR operation\&. .RE .sp .LP All operations except for \fBdelete\fR and \fBdrop\fR 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\&. .sp .LP 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, \fB%(alias)\fR refers to the value of the action\'s \fBalias\fR attribute\&. .sp .LP Several synthetic attributes exist\&. Two are unique to \fBpkgmogrify\fR: .RS +4 .TP .ie t \(bu .el o \fBpkg\&.manifest\&.filename\fR refers to the name of the file in which the action was found\&. .RE .RS +4 .TP .ie t \(bu .el o \fBpkg\&.manifest\&.lineno\fR refers to the line on which the action was found\&. .RE .sp .LP Three synthetic attributes are similar to ones used in \fBpkg\fR: .RS +4 .TP .ie t \(bu .el o \fBaction\&.hash\fR refers to the hash value of the action if the action carries a payload\&. For actions with payloads, the \fBset\fR operation can change the hash of the action by operating on the \fBaction\&.hash\fR attribute\&. .RE .RS +4 .TP .ie t \(bu .el o \fBaction\&.key\fR refers to the value of the key attribute\&. .RE .RS +4 .TP .ie t \(bu .el o \fBaction\&.name\fR refers to the name of the action\&. .RE .sp .LP If the attribute whose value is requested does not exist, \fBpkgmogrify\fR exits with an error\&. To prevent exiting with an error, follow the attribute name with \fB;notfound=\fR and a value to substitute in place of the attribute value\&. For example, \fB%(alias;notfound=\'no alias\')\fR prints the value of the attribute \fBalias\fR if it exists, and prints \fBno alias\fR otherwise\&. .sp .LP If the attribute whose value is requested is multi-valued, each value is printed, separated by spaces\&. Similarly to the \fBnotfound\fR token, the tokens \fBprefix\fR, \fBsuffix\fR, and \fBsep\fR can be used to change this behavior\&. The string denoted by \fBprefix\fR is prepended to each value, the string denoted by \fBsuffix\fR is appended to each value, and \fBsep\fR is placed in between the suffix of one value and the prefix of the next\&. .sp .LP Similarly to action attributes, \fBpkgmogrify\fR directives can reference package attributes using braces instead of parentheses: \fB%{pkg\&.fmri}\fR\&. At the point at which the transform directive is applied, the attribute must have been defined in a \fBset\fR action, or it is treated as \fBnotfound\fR, described above\&. When the processing reaches the end of the manifest file describing the package, the attributes are cleared for the next package\&. .sp .LP 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, \fBpkg\fR, is available (only in the context of \fBpkgmogrify\fR) for use in these situations\&. .sp .LP When \fBpkgmogrify\fR finishes reading a manifest specified on the command line and that manifest defined a \fBpkg\&.fmri\fR package attribute, \fBpkgmogrify\fR creates this synthetic \fBpkg\fR action, whose attributes are the package\'s attributes\&. A \fB\fR directive can then match on this action, just as it can match on any other action\&. .sp .LP Operations on a \fBpkg\fR 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 \fBpkg\fR action via the \fBadd\fR, \fBdefault\fR, or \fBset\fR operations does not result in a \fBset\fR action being added to the manifest, though it will be available for other \fB\fR directives to match on\&. Attempting to \fBemit\fR a \fBpkg\fR action causes an error\&. To add a package attribute, \fBemit\fR a \fBset\fR action instead\&. .sp .LP The third kind of substitution is a backreference\&. This substitution is not like the ones usable in the \fBedit\fR operation, but is a reference to groups listed in the transformation match on the left-hand side of the \fB->\fR\&. These are indicated by \fB%<1>\fR, \fB%<2>\fR, and so on, in the order seen in the matching criteria\&. .sp .LP The order of processing is as follows: .RS +4 .TP 1. Lines are read from input files\&. .RE .RS +4 .TP 2. Macros are applied\&. .RE .RS +4 .TP 3. \fB\fR and \fB\fR directives are processed, causing additional files to be found and read\&. .RE .RS +4 .TP 4. Once all input has been accumulated, each line in the input is converted into actions and all transforms applied\&. .RE .RS +4 .TP 5. Once processing is complete and successful, the output is written\&. .RE .SH EXAMPLES .LP \fBExample 1\fR Add Tags To SMF Manifests .sp .LP Add tags to Service Management Facility (SMF) manifests so they get imported when the package is installed on a live system\&. .sp .in +2 .nf \e add restart_fmri svc:/system/manifest-import:default> .fi .in -2 .sp .LP \fBExample 2\fR Move Files .sp .LP Move files from \fBusr/sfw/bin\fR to \fBusr/bin\fR\&. .sp .in +2 .nf edit path usr/sfw/bin usr/bin> .fi .in -2 .sp .LP \fBExample 3\fR Specify Reboot Needed .sp .LP Add \fBreboot-needed\fR tags to files under \fB/kernel\fR that are not \fB\&.conf\fR files\&. Note that this example leverages how transforms are applied to each action in the order seen in the input files\&. .sp .in +2 .nf set reboot-needed true> delete reboot-needed \&.*> .fi .in -2 .sp .sp .LP This can also be done in a single transform rule with regular expressions\&. .LP \fBExample 4\fR Convert FMRI Attribute To Depend Action .sp .LP Convert the package attribute \fBpkg\&.fmri\fR into a \fBdepend\fR action to become part of an incorporation\&. .sp .in +2 .nf \e emit depend type=incorporate fmri=%(value)> drop> .fi .in -2 .sp .LP \fBExample 5\fR Print a List of Bug Numbers .sp .LP Print a comma-separated list of quoted and prefixed bug numbers\&. .sp .in +2 .nf set name=bugs value=12345 value=54321 value=13579 value=97531 \e print %(value;sep=",";prefix="bug=\'";suffix="\'")> .fi .in -2 .sp .LP \fBExample 6\fR Allow For Missing Attributes .sp .LP Safely print a message even when an attribute is missing\&. .sp .in +2 .nf print Found aliases: %(alias;notfound=)> .fi .in -2 .sp .LP \fBExample 7\fR Set Default Values .sp .LP Set default owner, group, and permission values\&. .sp .in +2 .nf default owner root> default group bin> default mode 0444> default mode 0755> .fi .in -2 .sp .LP \fBExample 8\fR Add Dependencies To Packages That Are Not Marked Obsolete .sp .LP 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 \fBpkg\fR action has no permanent effect, there is no need to clean up attributes matching \fBpkg\&.obsolete=false\fR\&. .sp .in +2 .nf default pkg\&.obsolete false> emit depend \e fmri=consolidation/$(CONS)/$(CONS)-incorporation type=require> .fi .in -2 .sp .LP \fBExample 9\fR Exit and Print a Message When an Error Is Found .sp .LP Error out with a message when an obsolete attribute is found in a manifest\&. .sp .in +2 .nf \e exit 1 The opensolaris\&.zone attribute is obsolete\&.> .fi .in -2 .sp .LP \fBExample 10\fR Set the Appropriate Locale Facet .sp .LP Set the locale facet appropriate for the path name under consideration\&. .sp .in +2 .nf \e default facet\&.locale\&.%<1> true> .fi .in -2 .sp .SH EXIT STATUS .sp .LP The following exit values are returned: .sp .ne 2 .mk .na \fB\fB0\fR\fR .ad .RS 6n .rt Everything worked\&. .RE .sp .ne 2 .mk .na \fB\fB1\fR\fR .ad .RS 6n .rt Something bad but anticipated happened\&. .RE .sp .ne 2 .mk .na \fB\fB2\fR\fR .ad .RS 6n .rt Invalid command line options were specified\&. .RE .sp .ne 2 .mk .na \fB\fB99\fR\fR .ad .RS 6n .rt Unexpected processing error\&. .RE .SH FILES .sp .ne 2 .mk .na \fB\fB/usr/share/pkg/transforms\fR\fR .ad .br .sp .6 .RS 4n This directory contains files with useful transforms to set facets, actuators, and other attributes\&. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .TS tab( ) box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Availability \fBpackage/pkg\fR _ Interface Stability Uncommitted .TE .SH SEE ALSO .sp .LP \fBpkg\fR(1), \fBpkg\fR(5) .sp .LP \fBhttps://java\&.net/projects/ips/pages/Home\fR