Manual Pages for UNIX Operating System command usage for man pkgmogrify

User Commands                                            pkgmogrify(1)

NAME
     pkgmogrify - image packaging system manifest transmogrifier

SYNOPSIS
     /usr/bin/pkgmogrify [-vi] [-I includedir ...] [-D macro=value ...]
           [-O outputfile] [-P printfile] [inputfile ...]

DESCRIPTION
     pkgmogrify(1) provides for programmatic editing of package manifests
     to simplify the typical transformations needed when automating
     software builds and package publication.

     pkgmogrify(1) 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.

OPTIONS
     The following options are supported:

     -D name=value
          Defines "name" 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 pathnames, such as the
          name of the 64-bit architecture directory for executables and
          libraries:

              file NOHASH path=usr/bin/$(ARCH64)/cputrack ...

          Again, the expectation is that these macros would be set to the
          desired value on the command line; there are no predefined macro
          values.

     -I include_directory
          Adds the specified directory to the search path for both files
          specified on the command line and embedded include directives.

     -O outputfile
          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.

     -P printfile
          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.

     -i   Ignore include directives in files; only files specified on the
          command line (or stdin) are processed.

     -v   Write out comments into output manifest showing effect of
          transforms to aid debugging.

     --help or -?
          Displays a usage message.

EMBEDDED DIRECTIVES
     There are two types of directives supported in manifest files: include
     directives and transform directives.

     Include directives are of the form:

         

     This causes pkgmogrify(1) 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(1) exits with an error.

     Transform directives are of the form:

          operation>

     These 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-type ... ] [attribute= ...]

     One of the action-types specified must match.  All of the attributes
     specified must match.  The regular expression syntax used is that of
     Python; more information is available via the command "pydoc re" or
     (more completely) at http://docs.python.org/dev/howto/regex.html.  The
     regular expression is anchored at the beginning, but not the end, so
     the regular expression matching files by their extensions would have
     to include a leading ".*" and, for safety, a trailing "$".

     Multiple criteria may be specified, separated by spaces.

     The following operations are available:

     add       Add a value to an attribute.  Two arguments are taken.  The
               first is the name of the attribute, and the second is the
               value.

     default   Set the value of an attribute if it doesn't already exist.
               The same two arguments are taken as for "add".

     delete    Remove attribute values.  Two arguments are taken.  The
               first is the name of the attribute, and the second is a
               regular expression to match the attribute values deleted.
               Unlike the regular expression used to match an action, this
               expression is unanchored.

     drop      Discards this action.

     edit      Modifies an attribute of the action.  Three arguments are
               taken.  The first is the name of the attribute, the second
               is a regular expression matching the attribute value, and
               the third 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', etc., are available
               in the replacement string, if there are groups defined in
               the regular expression.

     emit      Emit a line to the manifest output stream.  This must be a
               valid action string, empty (which will result in a blank
               line), or a comment (a "#" followed by arbitrary text).

     exit      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     Print a message to the output file specified with -P.

     set       Set the value of an attribute.  The same two arguments are
               taken as for "add".

     All operations aside from "delete" and "drop" take (possibly optional)
     arguments whose contents will end up in the output stream.  These
     strings can contain three different kinds of special tokens which
     allow the output to contain information that isn't 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(1):
     pkg.manifest.filename and pkg.manifest.lineno.  These refer to the name
     of the file in which the action was found and the line on which it was
     found, respectively.  Three others are similar to ones used in pkg(1):
     action.hash, action.key, and action.name, which refer to the hash
     value of the action if the action carries a payload, the value of the
     key attribute, and the name of the action type, respectively.  For
     actions with payloads, the "set" operation can change the hash of the
     action by operating on the action.hash attribute.

     If the attribute whose value is requested doesn't exist, pkgmogrify(1)
     will exit with an error.  To prevent this, the attribute name may be
     followed by ";notfound=" and a value to substitute in its place.  For
     example "%(alias;notfound='no alias')" will print the value of the
     attribute "alias" if it exists, and "no alias" otherwise.

     If the attribute whose value is requested is multi-valued, each value
     will be printed, separated by spaces.  Similarly to the "notfound"
     token, the tokens "prefix", "suffix, and "sep" may 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(1) directives may 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(1)) for use in these situations.

     When pkgmogrify(1) finishes reading a manifest specified on the
     commandline and that manifest defined a "pkg.fmri" package attribute,
     it will create this synthetic "pkg" action, whose attributes are the
     package's attributes.  A  directive may then match on this
     action, just like any other action type.

     Operations on a "pkg" action are special, though, 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 will not result in a "set"
     action being added to the manifest, though it will be available for
     other  directives to match on.  Attempting to "emit" a
     "pkg" action will cause an error.  If you wish to add a package
     attribute, emit a "set" action instead.

     The third kind of substitution is a backreference, not like the ones
     usable in the "edit" operation, but a reference to groups listed in
     the transformation match on the left-hand side of the "->".  These are
     indicated by "%<1>", "%<2>", etc., in the order seen in the matching
     criteria.

     The order of processing is as follows:

     1) Lines are read from input file(s).
     2) Macros are applied.
     3)   and  directives are processed causing
        additional files to be found and read in.
     4) Once all input has been accumulated, each line in the input is
        converted into actions and all transforms applied.
     5) Once processing is complete and successful, the output is written.

EXAMPLES
     Example 1:  Add tags to SMF manifests so they get imported when the
     package is installed on a live system.

          \
             add restart_fmri svc:/system/manifest-import:default>

     Example 2:  Move files from usr/sfw/bin to usr/bin.

          edit path usr/sfw/bin usr/bin>

     Example 3:  Add "reboot-needed" tags to files under /kernel which
     aren't .conf files.  This can also be done in a single transform rule
     with regular expression magic, but this formulation will make more
     sense to most people.  Note that this leverages how transforms are
     applied to each action in the order seen in the input files.

          set reboot-needed true>
          delete reboot-needed .*>

     Example 4:  Convert the package attribute "pkg.fmri" into a depend
     action to become part of an incorporation.

          \
             emit depend type=incorporate fmri=%(value)>
          drop>

     Example 5:  Print a comma-separated list of quoted and prefixed bug
     numbers.

         set name=bugs value=12345 value=54321 value=13579 value=97531
          \
             print %(value;sep=",";prefix="bug='";suffix="'")>

     Example 6:  Safely print a message even when an attribute is missing.

          print Found aliases: %(alias;notfound=)>

     Example 7:  Set some default permissions.

          default owner root>
          default group bin>
          default mode 0444>
          default mode 0755>

     Example 8:  For any package which isn't marked obsolete, add a
     dependency on the incorporation for the consolidation that delivers
     it.  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".

          default pkg.obsolete false>
          emit depend \
             fmri=consolidation/$(CONS)/$(CONS)-incorporation type=require>

     Example 9:  Error out with a message when an obsolete attribute is
     found in a manifest.

          \
             exit 1 The opensolaris.zone attribute is obsolete.>

     Example 10: Set the locale facet appropriate for the pathname under
     consideration.

          \
             default facet.locale.%<1> true>

EXIT STATUS
     The following exit values are returned:

     0     Everything worked.

     1     Something bad but anticipated happened.

     2     Invalid command line options were specified.

     99    Unexpected processing error

ATTRIBUTES
     See attributes(5) for descriptions of the following attributes:
     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWipkg                    |
    |                             | pkg:/package/pkg            |
    |_____________________________|_____________________________|
    | Interface Stability         | None / Under Development    |
    |_____________________________|_____________________________|

SEE ALSO
     pkg(1), attributes(5), pkg(5)

NOTES
     The image packaging system is an under-development feature.
     Command names, invocation, formats, and operations are all subject
     to change.  Development is hosted in the OpenSolaris community
     at

     http://hub.opensolaris.org/bin/view/Project+pkg/