docs/reference/patches-conf-example.btft

[table class="topnav"]
[tr]
[td class="logotab"]mp[e]
[td][see name="index"]index[e][e]
[td][see name="guide/index"]guide[e][e]
[td][see name="reference/index"]reference[e][e]
[e]
[e]
 
[h1]patches.conf.example[e]
 
[quote class="note"]
generated from patches.conf.example -- do not edit this page directly, edit that file and regenerate ("mk . d" / "sh mk/d.sh") instead. see [see name="reference/config"]reference/config[e] for the narrative tour this page doesn't replace.
[e]
 
patches.conf -- an OPTIONAL, per-port file for advanced patch management. lives at <portdir>/patches/patches.conf, next to the .patch files it describes (a port-authoring file, in the ports tree -- see mp.conf.example, this file's sibling, for mp's own runtime config, including hooks.conf.example's closely-related IF_USE/AFTER grammar for hooks instead of patches). nothing here is required: a port with a patches/ directory and no patches.conf just applies every *.patch file in it, in filename order, unconditionally -- exactly as before this file existed. patches.conf only ADDS conditions and reordering on top of that, for the patches that actually need them.
 
a patch is named by its path relative to patches/ itself:
 
[code]
  003-fix.patch                    a plain, top-level patch
  use-ssl/002-extra.patch          one already inside a USE-flag
                                   directory (see "the existing
                                   directory conventions" below)
[e]
 
same "<name>:" section grammar as mp.conf itself -- an indented key under a patch's own header applies to just that one patch:
 
[code]
  003-fix.patch:
      IF_DEP=%zlib !experimental-thing
      IF_VER=>=2.0
      IF_USE=ssl
      AFTER=001-base.patch
[e]
 
[code]
IF_DEP=<token> <token> ...
  Every listed token must be among the port's actual effective
  dependencies (pkg_deps/pkg_bdepend/pkg_rdepend, DEPS/DEPS+/DEPS-
  overrides and USE-flag-contributed deps all included) for this patch
  to apply. a leading '!' requires the token's ABSENCE instead. matches
  either the bare or '%'-prefixed form of a %tag dependency, so
  "IF_DEP=zlib" and "IF_DEP=%zlib" both match a "pkg_deps=%zlib"
  dependency -- write whichever reads naturally.
    IF_DEP=%openssl            only if this port depends on %openssl
    IF_DEP=!bundled-zlib       only if it does NOT depend on bundled-zlib
[e]
 
[code]
IF_VER=<op><value> <op><value> ...
  the port's own pkg_ver must satisfy every listed constraint (the
  same op grammar as any dep token: >=, <=, >, <, =, ~). useful when
  one port directory builds several versions (its fetch/build phase
  keying off pkg_ver) and only some of them need a given patch:
    IF_VER=<2.0                only for versions older than 2.0
    IF_VER=>=1.5 <3.0          only for versions in [1.5, 3.0)
[e]
 
[code]
IF_USE=<flag> <flag> ...
  Same flag/!flag grammar as HOOKS_DIR/<phase>/hooks.conf's IF_USE
  (see hooks.conf.example) -- lets a flat, top-level patches/*.patch be
  USE-gated too, without moving it into a use-<flag>/ subdirectory:
    IF_USE=ssl                 only if USE=ssl is enabled for this port
    IF_USE=!debug              only if USE=debug is NOT enabled
[e]
 
[code]
DEPS+=<dep> <dep> ...
  Extra dependencies, in the same syntax as a plain pkg_deps entry
  (a name, a name with a version constraint, or a %tag), added to the
  port's effective dependency list whenever THIS patch is actually
  applied -- i.e. whenever its own IF_DEP/IF_VER/IF_USE conditions (if
  any) are satisfied. this is what lets a patch's own condition drive
  an extra dependency directly, instead of writing the same condition
  twice (once on the patch, once via pkg_use's "flag:dep" gating, kept
  in sync by hand) -- and it works for any condition a patch can carry,
  not just IF_USE:
    001-old-api-compat.patch:
        IF_VER=<2.0
        DEPS+=libcompat-old
  a USE-flag-gated patch that itself needs an extra library:
    use-x11/002-extra-backend.patch:
        DEPS+=libxcb
  (the patch already only applies when USE=x11 is enabled, via the
  use-x11/ directory convention -- no separate IF_USE= needed here,
  DEPS+= just rides along with whatever condition already gated it.)
  evaluated against the port's OWN naturally-declared deps (pkg_deps/
  pkg_bdepend/pkg_rdepend/pkg_use/DEPS overrides) -- never against
  anything another patch's own DEPS+= adds, so the result never depends
  on patch evaluation order and can never cycle.
[e]
 
[code]
AFTER=<patch> <patch> ...
  ordering prerequisite(s) among the patches actually being applied,
  topologically sorted. filename order is still the default/tiebreak
  for anything with no AFTER (and the whole file's default when there's
  no patches.conf at all), so most ports never need this -- it's for
  the case where two patches must apply in a specific order that
  filename sorting doesn't already give you, or where a later-added
  patch needs to slot in ahead of an earlier-numbered one:
    004-extra.patch:
        AFTER=001-base.patch 002-needs-dep.patch
  An AFTER edge to a patch that IF_DEP/IF_VER/IF_USE filtered out (or
  that just isn't in this port's patch list at all) is silently
  ignored -- AFTER only orders among what's actually being applied. A
  genuine ordering cycle (patch A after B, B after A) is a hard error,
  not a hang or a silent partial application.
[e]
 
the existing directory conventions still work exactly as before, and compose cleanly with everything above:
 
[code]
  patches/*.patch                 unconditional, sorted by filename
  patches/use-<flag>/*.patch      only when <flag> is enabled
  patches/nouse-<flag>/*.patch    only when <flag> is disabled (including
                                  never declared)
[e]
 
patches.conf can add IF_DEP/IF_VER/AFTER to a patch discovered through any of these, by naming its full relative path (e.g. "use-ssl/002-extra.patch:") -- it never changes WHETHER a directory- gated patch is discovered in the first place, only what happens to it once it has been.
 
a port with an explicit, hand-written patch: phase in its own pkg.conf is entirely unaffected by any of this -- patches.conf (like the plain directory conventions) only ever applies to a SYNTHESIZED patch phase, never overrides one the port wrote itself.
 
a full worked example: a USE flag that gates a patch, a dependency, AND a hook all together, one port declaring a "gui" feature that swaps in an X11 backend.
 
[code]
  pkg.conf:
    pkg_slot_use="gui"                  # gui on/off coexist as two slots
    pkg_use="gui"                       # declares the flag (no inline deps --
                                         # this patch's own DEPS+= supplies them)
[e]
 
[code]
  patches/patches.conf:
    use-gui/010-x11-backend.patch:
        DEPS+=libxcb libx11             # only pulled in when this patch applies
[e]
 
[code]
  (patches/use-gui/010-x11-backend.patch itself only ever applies when
  USE=gui is enabled, via the existing use-<flag>/ directory convention)
[e]
 
[code]
  HOOKS_DIR/post_install/hooks.conf:
    10-register-gui-backend:
        IF_USE=gui                      # same flag, independent mechanism
[e]
 
turning USE=gui on for this port (globally, or in a per-package section in mp.conf -- see mp.conf.example's own USE= docs) makes all three fire together: the patch applies, libxcb/libx11 join its dependency list, and the hook runs after install -- three independent mechanisms (a patch condition, patches.conf's own DEPS+=, and a hooks.conf IF_USE=) all reading the exact same enabled_use() state, so they can never disagree with each other about whether "gui" is on for this install.