$Id: patches,v 1.10 2021/11/23 02:53:38 nanons Exp $

Applying custom patches to ports
================================

To modify ports without messing up your CVS repository, copy the port
directory to /usr/ports/mystuff/CATEGORY, where CATEGORY is the port's
subdirectory.  "mystuff" is a special directory that the ports tree
ignores by default.

For example, with dwm:

	$ cd /usr/ports
	$ mkdir -p mystuff/x11
	$ cp -Rp x11/dwm mystuff/x11

Also copy the master Makefiles to easily build all packages:

	$ cp -p x11/Makefile mystuff/x11
	$ cp -p Makefile mystuff

To protect a patched package from getting overriden when updating, add
to its Makefile (with dwm, to /usr/ports/mystuff/x11/dwm/Makefile):

	REVISION= 999

This will not prevent changes to the upstream version from overriding
it, only local changes to the OpenBSD ports tree.  However, this is a
a good notification that you should update your copy.

Patch files that are added in the patches/ directory must start with
"patch-" for the ports infrastructure to apply them.

Writing patches
===============

To manually write your own patches, change to the port's directory and
download, extract, and apply all the existing patches:

	$ make patch NO_DEPENDS=y

Change to the port's build directory and build user:

	$ cd $(make show=WRKBUILD)
	$ doas -su _pbuild

Backup the files you intend to edit with an ".orig" suffix:

	$ cp file.c file.c.orig

Now make your changes to the port.

	$ vi file.c

Then exit the build user's doas(1) shell, go back to the port directory
and generate new patches from your changes that will be applied next
time you build:

	$ cd -
	$ make update-patches

This will modify the existing patches, so the "mystuff" method should
be used to avoid CVS conflicts.

Fetching patches
================

To automatically fetch patch files from the internet when building, use
the PATCHFILES variable (see bsd.port.mk(5)).  If the patch is not on
the MASTER_SITES, you'll have to define MASTER_SITES0, MASTER_SITES1,
etc. and append ":0", ":1" to the patch filename, corresponding to
which site to fetch from.

For example, to fetch and apply the "noborder" patch for dwm:

	MASTER_SITES0 = https://dwm.suckless.org/patches/
	PATCHFILES = {noborder/}dwm-noborder-${V}.diff:0
	PATCH_DIST_STRIP = -p1

Here:
* ${V} is the version of dwm, defined earlier in the Makefile.
* The brackets around "noborder/" will strip the leading subdirectory from
  the filename (see explanation under DISTFILES in bsd.port.mk(5))
* PATCH_DIST_STRIP is a list of options passed to patch(1) to ignore
  the "a/" and "b/" prefix from the "a/filename", "b/filename" used
  inside the patch file.

After modifying the Makefile, download and create checksums for the new
patch files:

	$ make makesum

