Re: workflow for managing ports patches against /usr/ports in poudriere

On Fri, 27 Mar 2026 17:06:36 +0100
Juraj Lutter <[email protected]> wrote:

> > On 27. Mar 2026, at 16:52, Lexi Winter <[email protected]> wrote:
> > 
> > void wrote in <acal_3lhCUYvXjwj@int21h>:
> >> On IRC I've been advised to use overlays for this.
> >> So let's say there's a port and the patches for it aren't in the tree.
> >> I download a fresh ports tree, null mount it and make that my overlay tree.
> >> Then strip out all the ports I don't want to patch, then patch the port in the
> >> overlay.
> >> 
> >> Then
> >> 
> >> poudriere bulk -j builder -p /usr/ports -O overlay category/patched-port
> >> 
> >> is this correct? Or is the patch just put somewhere in the overlay tree?
> >> Or is there some documentation explaining exactly what to do?
> >> I have around five or so ports needing patches and the patches aren't in the
> >> official tree yet.
> > 
> > i just have /usr/ports configured as a null ports tree:
> > 
> > # poudriere ports -c -p default -m null -M /usr/ports
> > 
> > then i can do whatever i want with /usr/ports (update from git, apply
> > local patches, whatever) and Poudriere just uses whatever is there.
> > 
> > from what i understand, i don't think overlays is the right way to go
> > here.
> 
> 
> Overlays are handy if you keep your /usr/ports on tip of “main” branch, for example.
> 
> —
> Juraj Lutter
> [email protected]

Hi.

I think "it depends".

Overlay is handy to try something complexed and widespreaded-among-ports
changes prepared by someone others. Examples would be updated mozc and
compiz-reloaded overlays by Ken DEGUCHI.

  https://github.com/kdeguchi/mozc-ports

  https://github.com/kdeguchi/compiz-reloaded-ports

Testers can try it without polluting local ports tree.

On the other hand, overlays could easily cause troubles
when preparing patches to be posted to Bugzilla or Phabricator,
because files existing in underlying layers (including actual
ports tree at the bottom layer) but not in the overlay are
hidden, and easily missed to be deleted on merging.


And another thing for kmod ports.

If the under-developed ports are kmod ones, keeping one builder
jail 100% in sync with bare-metal for local uses, overlays are
needed to be used both on bare-metal builds (regardless legacy way
or using PORTS_MODULES) and poudriere.

At least on outdated version of ports-mgmt/poudriere-devel when
I've first tried overlays, configuring /etc/make.conf with
standard way caused poudriere to malfunction (errored out)
regardless configuring overlay as additional ports tree or not.

Finally I've found workaround and modified my writings here

  https://brew.bsd.cafe/TomAoki/Tips-and-Tricks/src/branch/main/poudriere/README.md

with notifying to Ken.

I have these lines in my /etc/make.conf to test above-mentioned
overlays both on bare-metal and poudriere.

   ===== Lines in /etc/make.conf =====

## Ports overlays to apply.
## Need commenting out on building using poudriere with -O option,
## so use conditional to defile only if poudriere is not in use.
.ifndef POUDRIERE_BUILD_TYPE
OVERLAYS=       /usr/local/overlays/kdeguchi/mozc-ports \
                /usr/local/overlays/kdeguchi/compiz-reloaded-ports
.endif

   ===== End lines in /etc/make.conf =====

This workaround would be far more important for kmod ports.
I think overlays would need more official writings, preferrably
in ports(7) manpage or (currently nonexistent) ports_overlay(7).

Note that overlay(3X) already exists and transferred to
curs_overlay(3X).


Basically, creating git branches for local changes would be
most straightforward. Patches to be submitted can be easily
generated by simply using git functionalities and pushed to
Phabricator using arcanist if enough familiar with git.

But this can cause mis-matches in "n" numbers with official
repo if working on src tree and mistakenly commit something
into any of "official" branches instead of local ones.
This is why I don't commit anything into local clone of
"not 100% mine" repos including FreeBSD ones.
(IIRC, at least one of official repo, maybe src, was re-created
as of mis-matches on its transision from Subversion.)


So my workflow for NVIDIA driver ports is like below.

For usual cases that no additions are done (modify or delete only):
  Simply use `git diff` (with -U999999 option for Phabricator)
  and remove anything unrelated (introduced by patches from others).


For special cases that some additions are needed:
  `git stash --include-untracked` to save all changes into stash.
  `git stash show -p --include-untracked` to extract all changes.
     (with -U999999 option for Phabricator)
  `git stash pop` to restore.
  and remove anything unrelated (introduced by patches from others).

Note that adding "-- <cat>/<port> <cat>/<port> ..." is handy for ports
to reduce noises.

TBH, my workflow would be tooooo paranoid for ports or docs.

Regards.

-- 
Tomoaki AOKI    <[email protected]>