svn commit: r45388 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting
Mathieu Arnold
mat at FreeBSD.org
Fri Aug 1 08:15:23 UTC 2014
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 @@
<para>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.</para>
+ saving a copy of the original file before making any changes
+ using a <filename>.orig</filename> suffix.</para>
<screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
- <sect2 xml:id="slow-patch-automatic">
- <title>Automatic Patch Generation</title>
+ <para>After all changes have been made, <command>cd</command> back
+ to the port directory. Use <command>make makepatch</command> to
+ generate updated patch files in the <filename>files</filename>
+ directory.</para>
+
+ <sect2 xml:id="slow-patch-rules">
+ <title>General Rules for Patching</title>
+
+ <para>Patch files are stored in <varname>PATCHDIR</varname>,
+ usually <filename>files/</filename>, from where they will be
+ automatically applied. All patches must be relative to
+ <varname>WRKSRC</varname>. Typically
+ <varname>WRKSRC</varname> is a subdirectory of
+ <varname>WRKDIR</varname>, the directory where the distfile is
+ extracted. Use <command>make -V WRKSRC</command> to see the
+ actual path. The patch names are to follow these
+ rules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Avoid having more than one patch modify the same file.
+ For example, having both
+ <filename>patch-foobar.c</filename> and
+ <filename>patch-foobar.c2</filename> making changes to
+ <filename>${WRKSRC}/foobar.c</filename> makes them fragile
+ and difficult to debug.</para>
+ </listitem>
+
+ <listitem>
+ <para>When creating names for patch files, replace slashes
+ (<literal>/</literal>) with two underscores
+ (<literal>__</literal>). For example, to patch a file
+ named <filename>src/freeglut_joystick.c</filename>, name
+ the corresponding patch
+ <filename>patch-src__freeglut_joystick.c</filename>. Do
+ not name patches like <filename>patch-aa</filename> or
+ <filename>patch-ab</filename>. Always use the path and
+ file name in patch names. Using <command>make
+ makepatch</command> automatically generates the correct
+ names.</para>
+ </listitem>
+
+ <listitem>
+ <para>A patch may modify multiple files if the changes are
+ related and the patch is named appropriately. For
+ example,
+ <filename>patch-add-missing-stdlib.h</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Only use characters <literal>[-+._a-zA-Z0-9]</literal>
+ for naming patches. In particular, <emphasis>do not use
+ <literal>::</literal> as a path separator,</emphasis>
+ use <literal>__</literal> instead.</para>
+ </listitem>
+ </itemizedlist>
- <para>When all the files have been modified, use <command>make
- makepatch</command> from the port directory to write updated
- patch files to the <filename>files</filename> directory of the
- port.</para>
+
+ <para>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.</para>
+
+ <para>If a file must be deleted, do it in the
+ <buildtarget>post-extract</buildtarget> target rather than as
+ part of the patch.</para>
</sect2>
<sect2 xml:id="slow-patch-manual">
<title>Manual Patch Generation</title>
+ <note>
+ <para>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.</para>
+ </note>
+
<para>Patches are saved into files named
<filename>patch-*</filename> where
<replaceable>*</replaceable> indicates the pathname of the
@@ -292,44 +363,21 @@
<screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen>
<para>When generating patches for new, added files,
- <option>-N</option> is added to tell &man.diff.1; to treat the
+ <option>-N</option> is used to tell &man.diff.1; to treat the
non-existent original file as if it existed but was
empty:</para>
<screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
- <para>Patch files are stored in <varname>PATCHDIR</varname>
- (usually <filename class="directory">files/</filename>, from
- where they will be automatically applied. All patches must be
- relative to <varname>WRKSRC</varname> (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,
- <filename>patch-file</filename> and
- <filename>patch-file2</filename> both changing
- <filename>WRKSRC/foobar.c</filename>). Note that in the path
- of a patched file the <literal>/</literal> are to be replaced
- with two underscores <literal>__</literal>. For example, to
- patch a file named
- <filename>src/freeglut_joystick.c</filename>, the
- corresponding patch should be named
- <filename>patch-src__freeglut_joystick.c</filename>.</para>
-
- <para>Please only use characters
- <literal>[-+._a-zA-Z0-9]</literal> for naming patches. Do not
- use any other characters besides them. Do not name patches
- like <filename>patch-aa</filename> or
- <filename>patch-ab</filename>, always mention the path and
- file name in patch names.</para>
-
- <para>Do not put RCS strings in patches.
- <application>Subversion</application> 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
- (<literal>$</literal>) signs, and typically start with
- <literal>$Id</literal> or
- <literal>$RCS</literal>.</para>
+ <para>Do not add <literal>$FreeBSD$</literal> RCS strings in
+ patches. When patches are added to the
+ <application>Subversion</application> repository with
+ <command>svn add</command>, the
+ <literal>fbsd:nokeywords</literal> property is set to
+ <literal>yes</literal> automatically so keywords in the patch
+ are not modified when committed. The property can be added
+ manually with <command>svn propset fbsd:nokeywords yes
+ <replaceable>files...</replaceable></command>.</para>
<para>Using the recurse (<option>-r</option>) option to
&man.diff.1; to generate patches is fine, but please look at
@@ -348,26 +396,6 @@
</sect2>
- <sect2 xml:id="slow-patch-rules">
- <title>General Rules for Patching</title>
-
- <para>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 <application>Subversion</application> repository
- but makes it hard to find out what exactly caused the problem
- and what was changed at all.</para>
-
- <para>If a file must be deleted, do it in the
- <buildtarget>post-extract</buildtarget> target rather than as
- part of the patch.</para>
-
- </sect2>
-
<sect2 xml:id="slow-patch-automatic-replacements">
<title>Simple Automatic Replacements</title>
@@ -405,7 +433,7 @@ DOS2UNIX_FILES= util.c util.h</programli
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
- which invokes <command>find</command> for each element listed
+ which runs <command>find</command> for each element listed
in it.</para>
<programlisting>USES= dos2unix
More information about the svn-doc-head
mailing list