Date: Fri, 1 Aug 2014 08:15:22 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> 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 Message-ID: <201408010815.s718FMp1049539@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201408010815.s718FMp1049539>