Patch files are files created with the Unix command +diff+
that are applied using the command +patch+
to modify text files to fix bugs or extend functionality.
If you wish to contribute modifications or fixes to a Portfile, you should do so in the form of a patch. Follow the steps below to create Portfile patch files
Make a copy of the Portfile you wish to modify; both files must be in the same directory, though it may be any directory.
%% cp -p Portfile Portfile.orig
Now use the Unix command +diff -u +
to create a “unified” diff patch file. Put the name of the port in the patchfile, for example, Portfile-rrdtool.diff.
%% diff -u Portfile.orig Portfile > Portfile-rrdtool.diff
A patch file that is a “unified” diff file is the easiest to interpret by humans and this type should always be used for ports. The Portfile patch below will change the version and checksums when applied.
--- Portfile.orig 2011-07-25 18:52:12.000000000 -0700 +++ Portfile 2011-07-25 18:53:35.000000000 -0700 @@ -2,7 +2,7 @@ PortSystem 1.0 name foo -version 1.3.0 +version 1.4.0 categories net maintainers nomaintainer description A network monitoring daemon. @@ -13,9 +13,9 @@ homepage http://rsug.itd.umich.edu/software/${name} master_sites ${homepage}/files/ -checksums rmd160 f0953b21cdb5eb327e40d4b215110b71 +checksums rmd160 01532e67a596bfff6a54aa36face26ae extract.suffix .tgz platforms darwin
Now you may attach the patch file to a MacPorts Trac ticket for the port author to evaluate.
Necessary or useful patches to application source code should generally be sent to the application developer rather than the port author so the modifications may be included in the next version of the application.
Generally speaking, you should create one patch file for each logical change that needs to be applied.
Patchfile filenames should uniquely distinguish the file and generally be of the form patch-
<identifier>
.diff
, where the identifier
is a reference to the problem or bug it is supposed to solve.
An example filename would be patch-
destdir-variable-fix
.diff
.
To create a patch to modify a single file, follow the steps below.
Locate the file you wish to patch in its original location within the unpacked source directory and make a duplicate of it.
%% cd ~/Downloads/foo-1.34/src %% cp -p Makefile.in Makefile.in.orig
Now +cd+
to the top-level directory of the unpacked source, and use the Unix command +diff -u+
to create a “unified” diff patch file.
%% cd ~/Downloads/foo-1.34 %% diff -u src/Makefile.in.orig src/Makefile.in > patch-destdir-variable-fix.diff
You should execute +diff+
from the top-level directory of the unpacked source code, because during the patch phase MacPorts by default uses the patch argument +-p0+
, which does not strip prefixes with any leading slashes from file names found in the patch file (as opposed to -p1
that strips one, etc), and any path not relative to the top-level directory of the unpacked source will fail during the patch phase.
If you find an existing source file patch you wish to use that contains leading path information (diff was executed from a directory higher than the top-level source directory), you will need to use the patch phase keyword+patch.pre_args+
to specify a -px
value for how many prefixes with leading slashes are to be stripped off.
A patch file that is a “unified” diff file is the easiest to interpret by humans and this type should always be used for ports. See the example below where a patch adds DESTDIR
support to Makefile.in
.
--- src/Makefile.in.orig 2007-06-01 16:30:47.000000000 -0700 +++ src/Makefile.in 2007-06-20 10:10:59.000000000 -0700 @@ -131,23 +131,23 @@ $(INSTALL_DATA)/gdata $(INSTALL_DATA)/perl install-lib: - -mkdir -p $(INSTALL_LIB) + -mkdir -p $(DESTDIR)$(INSTALL_LIB) $(PERL) tools/install_lib -s src -l $(INSTALL_LIB) $(LIBS) - cp $(TEXT) $(INSTALL_LIB)/ + cp $(TEXT) $(DESTDIR)$(INSTALL_LIB)/
Place the patch patch-destdir-variable-fix.diff
in the directory ${portpath}/files
and use it in a port using the patchfiles
keyword. ${portpath}
may be in a local Portfile repository during development, or files/
may be in a port’s ${portpath}
in the global MacPorts repository.
patchfiles patch-destdir-variable-fix.diff
MacPorts applies patch files automatically, but you may want to know how to apply patch files manually if you want to test patch files you have created or you wish to apply uncommitted Portfile patches.
Change to the directory containing the file to be patched. In this example, we’ll apply a Portfile patch to the postfix port.
%% cd $(port dir postfix)
Now apply the patch from your Downloads folder, or wherever you put it. The patchfile knows the name of the file to be patched.
%% patch -p0 < ~/Downloads/Portfile-postfix.diff
patching file Portfile