From owner-svn-doc-head@FreeBSD.ORG Thu Feb 6 16:49:51 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 032E5611; Thu, 6 Feb 2014 16:49:51 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id E109A1A95; Thu, 6 Feb 2014 16:49:50 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s16GnoLa024241; Thu, 6 Feb 2014 16:49:50 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s16Gnoc7024240; Thu, 6 Feb 2014 16:49:50 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402061649.s16Gnoc7024240@svn.freebsd.org> From: Warren Block Date: Thu, 6 Feb 2014 16:49:50 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43805 - head/en_US.ISO8859-1/books/porters-handbook X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Feb 2014 16:49:51 -0000 Author: wblock Date: Thu Feb 6 16:49:50 2014 New Revision: 43805 URL: http://svnweb.freebsd.org/changeset/doc/43805 Log: Add examples of using diff(1), move mention of makepatch into that section. PR: docs/186499 Submitted by: Ondra Knezour Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Feb 6 16:03:48 2014 (r43804) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Feb 6 16:49:50 2014 (r43805) @@ -756,21 +756,43 @@ PLIST_DIRS= lib/X11/onekoPatching In the preparation of the port, files that have been added - or changed can be picked up with a &man.diff.1; for later - feeding to &man.patch.1;. Each patch you wish to apply should - be saved into a file named + or changed can be recorded with &man.diff.1; for later + feeding to &man.patch.1;. Doing this with a typical file + involves saving a copy of the original file before making any + changes. + + &prompt.user; cp file file.orig + + Patches are + saved into files named patch-* where * indicates the pathname of the file that is patched, such as patch-Imakefile or - patch-src-config.h. These files should - be stored in PATCHDIR (usually - files/, from where they will be + patch-src-config.h. + + After the file has been modified, &man.diff.1; is used to + record the differences between the original and the modified + version. causes &man.diff.1; to produce + unified diffs, the preferred form. + + &prompt.user; diff -u file.orig file > patch-pathname-file + + When generating patches for new, added files, + is added to tell &man.diff.1; to treat the + non-existent original file as if it existed but was + empty: + + &prompt.user; diff -u -N newfile.orig newfile > patch-pathname-newfile + + Patch files are + stored in PATCHDIR (usually + files/, from where they will be automatically applied. All patches must be relative to - WRKSRC (generally the directory your port's + WRKSRC (generally the directory the port's tarball unpacks itself into, that being where the build is - done). To make fixes and upgrades easier, you should avoid - having more than one patch fix the same file (e.g., + done). To make fixes and upgrades easier, avoid + having more than one patch fix the same file (that is, patch-file and patch-file2 both changing WRKSRC/foobar.c). @@ -788,6 +810,13 @@ PLIST_DIRS= lib/X11/onekopatch-ab etc, always mention the path and file name in patch names. + There is an alternate, easier method for creating patches to existing files. + The first steps are the same, make a copy of the unmodified file with an + .orig extension, then make modifications. + Then use make makepatch + to write updated patch files to the + files directory of the port. + Do not put RCS strings in patches. Subversion will mangle them when we put the files into the ports tree, and when we check them out @@ -798,23 +827,23 @@ PLIST_DIRS= lib/X11/oneko$RCS. Using the recurse () option to - &man.diff.1; to generate patches is fine, but please take a - look at the resulting patches to make sure you do not have any + &man.diff.1; to generate patches is fine, but please + look at the resulting patches to make sure there is no unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should - be deleted. If you had to edit + be deleted. If it was necessary to edit configure.in and run autoconf to regenerate configure, do not take the diffs of configure (it often grows to a few thousand - lines!); define USE_AUTOTOOLS=autoconf:261 + lines!). Instead, define USE_AUTOTOOLS=autoconf:261 and take the diffs of configure.in. - Also, try to minimize the amount of non-functional - whitespace changes in your patches. It is common in the Open + Try to minimize the amount of non-functional + whitespace changes in patches. It is common in the Open Source world for projects to share large amounts of a code base, but obey different style and indenting rules. If you take a working piece of functionality from one project to fix @@ -822,7 +851,7 @@ PLIST_DIRS= lib/X11/onekoSubversion repository but makes it - hard to find out what exactly caused the problem and what you + hard to find out what exactly caused the problem and what was changed at all. If you had to delete a file, then you can do it in the @@ -865,13 +894,6 @@ DOS2UNIX_REGEX= .*\.([ch]|cpp)USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h - - If you want to create a patch file based off of an - existing file, you can copy it with an - .orig extension, and then modify the - original one. The makepatch target - will write out an appropriate patch file to the - files directory of the port.