pkg_patch produces patch files which are tarred and compressed (currently with bz2) archives containing metadata and data files.
Note: unless otherwise specified, "package name" means full package name, including its version (but excluding any path information and the archive suffix). For example, apache-2.2.13 is a package name. As the current port/package infrastructure does not explicitly separate the version information out from the package name, there is some small room for confusion while parsing.
pkg_patch introduces two files with the following common format:
pkg_patch metadata file format
Files are text files in UTF-8 encoding, with Unix ("\n") line endings. Lines have different meanings depending on how they start:
Empty lines - Skipped, ignored
Lines starting with # ("hash" character) - Skipped, ignored
Lines starting with @ ("at" character) - Contain metadata. The exact format varies on specific metadata types, but generally can be described by the regex: "@(\w+) (.+)". The first part will be referenced as "name" and everything after the space as "argument".
This format is used in the following files:
+PKGPATCH
This files is embedded in the package patch files, along other metadata files taken from the "target" package. It describes the difference in content of two package files. It contains the following metadata items:
@version - Package patch infrastructure version. The argument is described by the regex "\d+\.\d+". Can appear only once in the metadata file.
@source - Source package name (which this patch file upgrades). The argument is the package name string. Can appear only once in the metadata file.
@target - Target package name (to which this patch file upgrades). The argument is the package name. Can appear only once in the metadata file.
@add - Filename of a file to add to the package. The argument is the filename.
@remove - Filename of a file to remove from the package. The argument is the filename.
@rmdir - Directory name to remove. The argument is the directory name.
@patch - Filename of the file to patch within the package. The metadata information contains optional attributes and the full format of the metadata line can be described as: "@patch [method=(\w+)] (.+)". The "method" attribute can be one of: "cp", "ln", "bsdiff". The "cp" patch method patches the file simply by copying it (i.e. including the full target version of the file to patch in the patch), the "ln" is similar to cp but for symlinks (copies symlink pointer) and the "bsdiff" method is when the bsdiff(1) utility is used for patch file generation. The rest of the line after the attributes contains the filename. The patch file treated with the "bsdiff" method has a filename equaling to the original filename with the ".bsdiff" suffix added.
Note that the metadata file contains paths relative to the package archive contents, as do other similar metadata files within the packages, but the real filenames are derived from +CONTENTS files (using its "cwd" information).
A sample +PKGPATCH file is:
# FreeBSD package patch archive created on Mon Aug 9 02:59:08 2010 @version 1.0 @source libiconv-1.13.1 @target libiconv-1.13.1_1 @patch [method=cp] libdata/charset.alias @patch [method=cp] lib/libiconv.so.3 @patch [method=ln] lib/libiconv.so @patch [method=cp] lib/libiconv.la @patch [method=cp] lib/libiconv.a @patch [method=cp] lib/libcharset.so.1 @patch [method=ln] lib/libcharset.so @patch [method=cp] lib/libcharset.la @patch [method=cp] lib/libcharset.a @patch [method=cp] bin/iconv
The result of applying the +PKGPATCH file to the source package archive contents is to transform it into the target package archive contents.
PKGPATCHINDEX
This file appears in the root of on-line (web-based) package patch repository and describes available patches in the repository.
It contains the following metadata items:
@version - Package patch infrastructure version. The argument is described by the regex "\d+\.\d+". Can appear only once in the metadata file. This item should be equal to the metadata item from +PKGPATCH file of the same name.
@pkgrepo - Specifies the package repository (the full package repository) for the target packages. It is used when a package patch introduces a new dependancy not present in the source packages. Can appear only once in the metadata file.
@havepatch - Description of an available patch. Its argument contains four space-separated strings:
- Source package name
- Destination package name
- Patch package filename
- ISO8601-compliant timestamp of the patch creation
A sample PKGPATCHINDEX file is:
# Created by mkpatchdir at Mon Aug 9 02:58:21 2010 @version 1.0 @pkgrepo ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/All/ @havepatch apache-2.2.13 apache-2.2.15_9 apache-2.2.13-2.2.15_9.tbz 2010-08-09T00:58:29Z @havepatch expat-2.0.1 expat-2.0.1_1 expat-2.0.1-2.0.1_1.tbz 2010-08-09T00:58:29Z @havepatch perl-5.8.9_3 perl-5.10.1_1 perl-5.8.9_3-5.10.1_1.tbz 2010-08-09T00:59:05Z @havepatch pcre-7.9 pcre-8.02 pcre-7.9-8.02.tbz 2010-08-09T00:59:07Z @havepatch libiconv-1.13.1 libiconv-1.13.1_1 libiconv-1.13.1-1.13.1_1.tbz 2010-08-09T00:59:09Z
The filenames are relative to the location of the PKGPATCHINDEX file.