From owner-svn-doc-all@FreeBSD.ORG Fri Aug 1 08:15:22 2014 Return-Path: Delivered-To: svn-doc-all@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 E3D43BEC; Fri, 1 Aug 2014 08:15:22 +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)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id D040B28EB; Fri, 1 Aug 2014 08:15:22 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s718FMJ6049540; Fri, 1 Aug 2014 08:15:22 GMT (envelope-from mat@svn.freebsd.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s718FMp1049539; Fri, 1 Aug 2014 08:15:22 GMT (envelope-from mat@svn.freebsd.org) Message-Id: <201408010815.s718FMp1049539@svn.freebsd.org> From: Mathieu Arnold Date: Fri, 1 Aug 2014 08:15:22 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45388 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 01 Aug 2014 08:15:23 -0000 Author: mat (ports committer) Date: Fri Aug 1 08:15:22 2014 New Revision: 45388 URL: http://svnweb.freebsd.org/changeset/doc/45388 Log: Reword the patch creation section. Reviewed by: wblock Sponsored by: Absolight Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Fri Aug 1 04:43:37 2014 (r45387) +++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Fri Aug 1 08:15:22 2014 (r45388) @@ -259,24 +259,95 @@ In the preparation of the port, files that have been added 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. + saving a copy of the original file before making any changes + using a .orig suffix. &prompt.user; cp file file.orig - - Automatic Patch Generation + After all changes have been made, cd back + to the port directory. Use make makepatch to + generate updated patch files in the files + directory. + + + General Rules for Patching + + Patch files are stored in PATCHDIR, + usually files/, from where they will be + automatically applied. All patches must be relative to + WRKSRC. Typically + WRKSRC is a subdirectory of + WRKDIR, the directory where the distfile is + extracted. Use make -V WRKSRC to see the + actual path. The patch names are to follow these + rules: + + + + Avoid having more than one patch modify the same file. + For example, having both + patch-foobar.c and + patch-foobar.c2 making changes to + ${WRKSRC}/foobar.c makes them fragile + and difficult to debug. + + + + When creating names for patch files, replace slashes + (/) with two underscores + (__). For example, to patch a file + named src/freeglut_joystick.c, name + the corresponding patch + patch-src__freeglut_joystick.c. Do + not name patches like patch-aa or + patch-ab. Always use the path and + file name in patch names. Using make + makepatch automatically generates the correct + names. + + + + A patch may modify multiple files if the changes are + related and the patch is named appropriately. For + example, + patch-add-missing-stdlib.h. + + + + Only use characters [-+._a-zA-Z0-9] + for naming patches. In particular, do not use + :: as a path separator, + use __ instead. + + - When all the files have been modified, use make - makepatch from the port directory to write updated - patch files to the files directory of the - port. + + 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. When taking a working + piece of functionality from one project to fix similar areas + in another, please be careful: the resulting patch may be full + of non-functional changes. It not only increases the size of + the ports repository but makes it hard to find out what + exactly caused the problem and what was changed at all. + + If a file must be deleted, do it in the + post-extract target rather than as + part of the patch. Manual Patch Generation + + Manual patch creation is usually not necessary. + Automatic patch generation as described earlier in this + section is the preferred method. However, manual patching + may be required occasionally. + + Patches are saved into files named patch-* where * indicates the pathname of the @@ -292,44 +363,21 @@ &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 + is used 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 - the port's tarball unpacks itself into, that being where the - build is 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). Note that in the path - of a patched file the / are to be replaced - with two underscores __. For example, to - patch a file named - src/freeglut_joystick.c, the - corresponding patch should be named - patch-src__freeglut_joystick.c. - - Please only use characters - [-+._a-zA-Z0-9] for naming patches. Do not - use any other characters besides them. Do not name patches - like patch-aa or - patch-ab, always mention the path and - file name in patch names. - - 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 - again, they will come out different and the patch will fail. - RCS strings are surrounded by dollar - ($) signs, and typically start with - $Id or - $RCS. + Do not add $FreeBSD$ RCS strings in + patches. When patches are added to the + Subversion repository with + svn add, the + fbsd:nokeywords property is set to + yes automatically so keywords in the patch + are not modified when committed. The property can be added + manually with svn propset fbsd:nokeywords yes + files.... Using the recurse () option to &man.diff.1; to generate patches is fine, but please look at @@ -348,26 +396,6 @@ - - General Rules for Patching - - 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. When taking a working - piece of functionality from one project to fix similar areas - in another, please be careful: the resulting line patch may be - full of non-functional changes. It not only increases the - size of the Subversion repository - but makes it hard to find out what exactly caused the problem - and what was changed at all. - - If a file must be deleted, do it in the - post-extract target rather than as - part of the patch. - - - Simple Automatic Replacements @@ -405,7 +433,7 @@ DOS2UNIX_FILES= util.c util.h A similar option is DOS2UNIX_GLOB, - which invokes find for each element listed + which runs find for each element listed in it. USES= dos2unix