Cross package maker. DEB/RPM generation or conversion. Derived from jordansissel/fpm.

⌈⌋ ⎇ branch:  cross package maker


Update of "update filters"

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: b20345f6312632bd6ec188a0f80fd619fae7c4ea
Page Name:update filters
Date: 2015-04-14 16:20:12
Original User: mario
Mimetype:text/x-markdown
Parent: 4fd8eb2cdc8080c89a043b5844a4fdd51c4070cb (diff)
Next 4d75beb6f990992f404a24e1d0570be5f63ff885
Content

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.
-u packfile Customize via external/packaged-in Packfile make script.

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.

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


  • -u packfile

    To make packaging hooks even more flexible, there's now a thing called Packfiles. 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 collected.

    Notably the Packfile can reside in the source directory (where fpm/xpm) was invoked from. But they're still run with the staging path set as current working directory. So it can easily add minor renames, 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 before the final target package is built.

    Why? I've noticed a few non-build steps creeping into a regular Makefile. Apart from the manpage compression, there was now gzip NEWS > changelog.gz just for lintian-clean DEB packages. While a few steps (GtkBuilder compression) did indeed belong to the "make" stage, others were really just workarounds for DEB or ZIP arrangements. - So now I've got an extra make script, and the regular Makefile still starts fpm of course. But there's now less mashup and interference between.

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