D 2015-02-14T11:33:24.796
L update\sfilters
N text/x-markdown
P 2729c66f1f1d360099a8f4867140320252c6d9ef
U mario
W 7471
Update filters are simple post-processing hooks. They're run after any input files have been collected, and before the target package is built.
<table width=70%>
<tr>
<td> <kbd><a href=wiki/update+filters#man>-u man</a></kbd> </td>
<td> Compresses man pages. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#appdata>-u appdata</a></kbd> </td>
<td> Creates <code>pkg.appdata.xml</code> for distro appcenters. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#desktop>-u desktop</a></kbd> </td>
<td> Adds a stub <code>fpm:pkg.desktop</code> file. </td>
</tr>
<tr>
<td> <kbd><nobr><a href=wiki/update+filters#composer>-u composer</a></nobr></kbd> </td>
<td> Update a `composer.json` for <kbd>phar</kbd> target. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#fixperms>-u fixperms</a></kbd> </td>
<td> Limit file permissions (<code>umask 755</code>).</td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#strip>-u strip</a></kbd> </td>
<td> Strip debugging symbols from binaries. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#deps>-u deps</a></kbd> </td>
<td> Resolve library/dependency names across distros. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#unprefix>-u unprefix</a></kbd> </td>
<td> Converting system package filenames to local paths. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#lcase>-u lcase</a></kbd> </td>
<td> Lowercase filenames and directories. </td>
</tr>
<tr>
<td> <kbd><a href=wiki/update+filters#preprocess>-u preprocess</a></kbd> </td>
<td> Expand preprocessing macros in source files. </td>
</tr>
</table>
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 <kbd>-u</kbd> or <kbd>--filter</kbd> flags.
* Some plugins take options separated by `=` from plugin name, as in <kbd>-u deps=fedora</kbd> or <kbd>-u lcase=*:php:rb</kbd>
Note that filters are applied just once on the input, not on each output package in a [multi-target](wiki/multi-target) build.
<br>
* <h2> <kbd><em>-u</em> man</kbd> <a name=man></a> </h2>
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.)
<br>
* <h2> <kbd><em>-u</em> appdata</kbd> <a name=appdata></a> </h2>
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/](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.
<br>
* <h2> <kbd><em>-u</em> desktop</kbd> <a name=desktop></a> </h2>
<small>State: <em>very crude</em>.</small>
With <kbd>-u desktop</kbd> 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.
<br>
* <h2> <kbd><em>-u</em> composer</kbd> <a name=composer></a> </h2>
When using the <kbd>[-t phar](wiki/phar)</kbd> module, you may wish to combine it with an implicit <kbd>-u composer</kbd> 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 <kbd>-s src</kbd> to <kbd>-t phar</kbd> 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 [<kbd>-s composer</kbd> source package](wiki/source_composer) plugin. The two have orthogonal use cases.
<br>
* <h2> <kbd><em>-u</em> lcase<xmp>=*</xmp></kbd> <a name=lcase></a> </h2>
Converts directory and filenames to lowercase.
* Directories are always lowercased.
* File extensions can be specified with <kbd>-u lcase=*</kbd> for all, or <kbd>lcase=php:cpp</kbd> for specific groups to lowercase.
This is meant just for the [<kbd>-t phar</kbd>](wiki/phar) target. It's probably less suitable for system packages.
<br>
* <h2> <kbd><em>-u</em> deps<xmp>=fedora</xmp></kbd> <a name=deps></a> </h2>
<small>State: <em>incomplete</em></small>
The <kbd>deps</kbd> 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.)
<br>
* <h2> <kbd><em>-u</em> unprefix</kbd> <a name=unprefix></a> </h2>
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.
<br>
* <h2> <kbd><em>-u</em> fixperms</kbd> <a name=fixperms></a> </h2>
<small>State: <em>redundant</em></small>
Applies umask 0755 to files. Which is somewhat redundant since both deb and rpm plugins already implement a variation thereof.
<br>
* <h2> <kbd><em>-u</em> strip</kbd> <a name=strip></a> </h2>
Strips debugging symbols from binaries.
* Is just applied to binaries.
* Skips shared libraries currently.
<br>
* <h2> <kbd><em>-u</em> preprocess<xmp>=py</xmp></kbd> <a name=preprocess></a> </h2>
Pipes source files through `preprocess.py` to expand macros. This is meant for scripting languages, not as C/C++ build hook.
The recognized comment syntax is based on the source language / file extensions.
* `# #define`
* `// #ifdef`
* `/* #include "file.ph" */`
* `<!-- #include "file.ph" -->`
It doesn't process literal C-macros.
* In-code substitutions of defined constants are enabled per default (preprocess <kbd>-s</kbd> flag).
* Expects a file extension list, such as <kbd>-u preprocess=pl:php:rb</kbd>.
* Requires `preprocess` to be available, which is packaged for Debian distros at least.
<br>
<style>
xmp { display: inline; }
kbd xmp { font-size: 80%; text-weight: 100; color: #888; }
</style>
Z 01e48387d2e5fe51bfcd91d1cb705738