D 2015-04-14T16:06:28.726
L update\sfilters
N text/x-markdown
P 9658f5e578324482faedf6bd0a2f557d43322c5f
U mario
W 8898
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>
<tr>
<td> <kbd><a href=wiki/update+filters#packfile>-u packfile</a></kbd> </td>
<td> Customize via external/packaged-in <kbd>Packfile</kbd> make script. </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.
* Notes
* 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>
* <h2> <kbd><em>-u</em> packfile</kbd> <a name=packfile></a> </h2>
To make packaging hooks even more flexible, there's now a thing called <b>`Packfile`</b>s. And a `Packfile` is basically a `Makefile`, and indeed run through `make`. Its purpose is however to collect *minor modification* steps. They're run within the **`/tmp/pack-xyz-staging/`** directory, after all "source" files have been colected.
Notably the `Packfile` can reside in the source directory (where fpm/xpm) is run from. But they're still run with the staging path set as current working directory. So it can add minor shifts, compress files, add stubs or inject defaults, etc. Of course this should be introduced carefully. It's precisely not meant to delay build tasks, but really just for mid-packaging hooks.
There are just a few environment variables predefined for the Packfile:
- `PACK_TYPE` = deb
- `PACK_NAME` = mypkg
- `PACK_VERSION` = 1.2.3
- `PACK_ARCH` = native
- `PACK_STAGING` = /tmp/pack-dir-staging-123/
And Packfiles that reside in the staging dir, in nested paths such as `/tmp/xyz-staging/usr/share/doc/Packfile` are run in-place, and automatically get stripped prior target package building.
<style>
xmp { display: inline; }
kbd xmp { font-size: 80%; text-weight: 100; color: #888; }
</style>
Z 730f9217dbedb87f8b6b85f23c27f7db