From owner-svn-doc-all@FreeBSD.ORG Wed Mar 5 15:23:52 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 5BB08534; Wed, 5 Mar 2014 15:23:52 +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 2CE28803; Wed, 5 Mar 2014 15:23:52 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s25FNqUs061666; Wed, 5 Mar 2014 15:23:52 GMT (envelope-from mat@svn.freebsd.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s25FNqRh061665; Wed, 5 Mar 2014 15:23:52 GMT (envelope-from mat@svn.freebsd.org) Message-Id: <201403051523.s25FNqRh061665@svn.freebsd.org> From: Mathieu Arnold Date: Wed, 5 Mar 2014 15:23:52 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44129 - 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.17 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: Wed, 05 Mar 2014 15:23:52 -0000 Author: mat (ports committer) Date: Wed Mar 5 15:23:51 2014 New Revision: 44129 URL: http://svnweb.freebsd.org/changeset/doc/44129 Log: Update the slow-porting chapter. 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 Wed Mar 5 14:23:30 2014 (r44128) +++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Wed Mar 5 15:23:51 2014 (r44129) @@ -100,9 +100,18 @@ + The package target is run. + This creates a package using the files from the temporary + directory created during the + stage target and the port's + pkg-plist. + + + The install target is run. - This copies the files listed in the port's pkg-plist to the - host system. + This install the package created during the + package target into the host + system. @@ -255,133 +264,153 @@ &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. - - 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 - 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 if the path of - a patched file contains an underscore (_) - character, the patch needs to have two underscores instead in - its name. 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. - - 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 - 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. - - Using the recurse () option to - &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 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!). Instead, define - USE_AUTOTOOLS=autoconf:261 and take the diffs - of configure.in. - - 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 replacements can be performed directly from the port - Makefile using the in-place mode of - &man.sed.1;. This is useful when changes use the value of a - variable: + + Automatic Patch Generation + + 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. + + + + + Manual Patch Generation + + 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. + + 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 + 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. + + Using the recurse () option to + &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 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!). Instead, define + USE_AUTOTOOLS=autoconf:261 and take the + diffs of configure.in. + + + + + 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 + + Simple replacements can be performed directly from the + port Makefile using the in-place mode of + &man.sed.1;. This is useful when changes use the value of a + variable: - post-patch: + post-patch: @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README - Quite often, software being ported uses the CR/LF convention - in source files. This may cause problems with further patching, - compiler warnings, or script execution (like - /bin/sh^M not found.) To quickly convert all - files from CR/LF to just LF, add this entry to the port - Makefile: + Quite often, software being ported uses the CR/LF + convention in source files. This may cause problems with + further patching, compiler warnings, or script execution (like + /bin/sh^M not found.) To quickly convert + all files from CR/LF to just LF, add this entry to the port + Makefile: - USES= dos2unix + USES= dos2unix - A list of specific files to convert can be given: + A list of specific files to convert can be given: - USES= dos2unix + USES= dos2unix DOS2UNIX_FILES= util.c util.h - Use DOS2UNIX_REGEX to convert a group of - files across subdirectories. Its argument is a - &man.find.1;-compatible regular expression. More on the format - is in &man.re.format.7;. This option is useful for converting - all files of a given extension. For example, convert all source - code files, leaving binary files intact: + Use DOS2UNIX_REGEX to convert a group + of files across subdirectories. Its argument is a + &man.find.1;-compatible regular expression. More on the + format is in &man.re.format.7;. This option is useful for + converting all files of a given extension. For example, + convert all source code files, leaving binary files + intact: - USES= dos2unix + USES= dos2unix DOS2UNIX_REGEX= .*\.([ch]|cpp) - A similar option is DOS2UNIX_GLOB, which - invokes find for each element listed in - it. + A similar option is DOS2UNIX_GLOB, + which invokes find for each element listed + in it. - USES= dos2unix + USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h +