1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions & Useful Tcl Commands
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Contributing to MacPorts
7.3. Port Update Policies
7.4. Updating Documentation
7.5. MacPorts Membership
7.6. The PortMgr Team
8. MacPorts Guide Terms
Glossary

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

  1. 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
  2. Edit the file to make it as you want it to be after it is fetched.

  3. 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
  4. 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 hint of what the patch does. For example, this can be the filename of the patched file as in patch-src-Makefile.in.diff.

You may use patch files that patch multiple files under these conditions:

  • You find existing patch files that do so.

  • If fixing a particular problem or bug requires changes in multiple files—in those cases the patch filename should reference the problem or bug, for example: patch-destdir-variable-fix.diff

To create a patch to modify a single file, follow the steps below.

  1. 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
  2. Edit the file and modify the text to reflect your corrections.

  3. 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-src-Makefile.in.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.

    Note

    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.

  4. 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)/
  5. Place the patch patch-src-Makefile.in.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-src-Makefile.in.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.

  1. 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)
  2. 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