diff --git a/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml index 15969ba45f..22cce6723d 100644 --- a/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml +++ b/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml @@ -99,10 +99,19 @@ installed. + + 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. + + Automatic Patch Generation - 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. + 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. - &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: + + Manual Patch Generation - &prompt.user; diff -u -N newfile.orig newfile > patch-pathname-newfile + 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. - 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. + 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. - 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. + &prompt.user; diff -u file.orig file > patch-pathname-file - 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. + 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: - 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. + &prompt.user; diff -u -N newfile.orig newfile > patch-pathname-newfile - 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. + 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. - 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. + 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. - If a file must be deleted, do it in the - post-extract target rather than as - part of the patch. + 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. - 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: + 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. - post-patch: + + + + 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: @${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 +