Update filters are simple post-processing hooks. They're run after any input files have been collected, and before the target package is built.

-u man	Compresses man pages.
-u appdata	Creates pkg.appdata.xml for distro appcenters.
-u desktop	Adds a stub fpm:pkg.desktop file.
-u composer	Update a composer.json for phar target.
-u fixperms	Limit file permissions (umask 755).
-u strip	Strip debugging symbols from binaries.
-u deps	Resolve library/dependency names across distros.
-u unprefix	Converting system package filenames to local paths.
-u lcase	Lowercase filenames and directories.
-u preprocess	Expand preprocessing macros in source files.

You'd usually run them with:

xpm  -s dir  -u man,appdata,desktop  -t deb  ...

They're intended for simple tasks.

• Can supplant build/make steps that rather belong into the packaging process.
• They're partly resembling debian-helpers.
• Can either be specified as comma-separated lists, or with multiple -u or --filter flags.
• Some plugins take options separated by = from plugin name, as in -u deps=fedora or -u lcase=*:php:rb

Note that filters are applied just once on the input, not on each output package in a multi-target build.

• -u man

  The "man" filter simply compresses manpages found in the staging path.

  • It looks for a man/ directory.
  • Searches for files ending in .1 or .2 or other numeric suffixes.

  It's intended to avoid that step in Makefiles. (As this is clearly a packaging thing.)

  
  

• -u appdata

  The "appdata" filter crafts a plain PKG.appdata.xml file. Those are used by the application managers/centers in most distributions. It's an agreed format between DEB and RPM-based distros, Listaller, etc.

  See http://www.freedesktop.org/wiki/Distributions/AppStream/

  A few things missing here:

  • We likely need a --screenshot flag. Those are the primary purpose of AppData/AppStream.
  • This filter will overwrite existing appdata.xml files. So don't use it, if you're already providing one.

  
  

• -u desktop

  State: very crude.

  With -u desktop an application icon file appname.desktop will be generated.

  • Don't use this update filter if you're already providing one.
  • It will be prefixed with fpm:appname to avoid collisions.

  
  

• -u composer

  When using the -t phar module, you may wish to combine it with an implicit -u composer update.

  • Writes current version etc. to composer.json

  • Creates a stub composer.json otherwise, containing:

    • name
    • description
    • license
    • homepage
    • type: Library
    • extra: [ Maintainer, Epoch, Releases (stub) ]
    • autoload (shared.phar)

  • No dependency translation is handled whatsoever currently. (This plugin is primarily meant for -s src to -t phar conversion. The php plugin meta data fields are somewhat broader than composer bundle specs; and the dependencies specifically more localized application/api-targeted. Besides there's no agreed mapping yet between composer and system packages.)

  Note that there's a distinct -s composer source package plugin. The two have orthogonal use cases.

  
  

• -u lcase<xmp>=*</xmp>

  Converts directory and filenames to lowercase.

  • Directories are always lowercased.
  • File extensions can be specified with -u lcase=* for all, or lcase=php:cpp for specific groups to lowercase.

  This is meant just for the -t phar target. It's probably less suitable for system packages.

  
  

• -u deps<xmp>=fedora</xmp>

  State: incomplete

  The deps filter is supposed to convert distro-specific package names. It utilizes whohas or distromatch. Since the latter is discontinued, it might make sense to just bundle a few package maps with xpm/fpm directly, and perform the lookup (for major distros) internally. (Would also be faster, really.)

  
  

• -u unprefix

  For extracing system package contents back into relative/local path structures you can use:

   xpm -s deb -u unprefix=/usr/share/appfiles/ -t zip pkgname.deb
  

  This will slice out just the files given below the base path as filter= argument.

  
  

• -u fixperms

  State: redundant

  Applies umask 0755 to files. Which is somewhat redundant since both deb and rpm plugins already implement a variation thereof.

  
  

• -u strip

  Strips debugging symbols from binaries.

  • Is just applied to binaries.
  • Skips shared libraries currently.

  
  

• -u preprocess<xmp>=py</xmp>

  Pipes source files through preprocess.py to expand macros. This is meant for scripting languages, not as C/C++ build hook.

  Depending on source language (file extension) it recognizes # #define or // #ifdef or the /* #include "file.ph" */ comment syntax, but not literal C-macros.

  • In-code substitutions of defined constants are enabled per default (preprocess -s flag).
  • Expects a file extension list, such as -u preprocess=pl:php:rb.
  • Requires preprocess to be available, which is packaged for Debian distros at least.

  
  

<style> xmp { display: inline; } kbd xmp { font-size: 80%; text-weight: 100; color: #888; } </style>