patches.conf.example

# 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:
#   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)
#
# same "<name>:" section grammar as mp.conf itself -- an indented key
# under a patch's own header applies to just that one patch:
#
#   003-fix.patch:
#       IF_DEP=%zlib !experimental-thing
#       IF_VER=>=2.0
#       IF_USE=ssl
#       AFTER=001-base.patch
#
# 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
#
# 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)
#
# 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
#
# 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.
#
# 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.
#
# the existing directory conventions still work exactly as before, and
# compose cleanly with everything above:
#   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)
# 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.
#
#   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)
#
#   patches/patches.conf:
#     use-gui/010-x11-backend.patch:
#         DEPS+=libxcb libx11             # only pulled in when this patch applies
#
#   (patches/use-gui/010-x11-backend.patch itself only ever applies when
#   USE=gui is enabled, via the existing use-<flag>/ directory convention)
#
#   HOOKS_DIR/post_install/hooks.conf:
#     10-register-gui-backend:
#         IF_USE=gui                      # same flag, independent mechanism
#
# 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.