Date: Thu, 6 Feb 2014 16:49:50 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43805 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201402061649.s16Gnoc7024240@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Thu Feb 6 16:49:50 2014 New Revision: 43805 URL: http://svnweb.freebsd.org/changeset/doc/43805 Log: Add examples of using diff(1), move mention of makepatch into that section. PR: docs/186499 Submitted by: Ondra Knezour <knezour@weboutsourcing.cz> Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Feb 6 16:03:48 2014 (r43804) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Feb 6 16:49:50 2014 (r43805) @@ -756,21 +756,43 @@ PLIST_DIRS= lib/X11/oneko</programlistin <title>Patching</title> <para>In the preparation of the port, files that have been added - or changed can be picked up with a &man.diff.1; for later - feeding to &man.patch.1;. Each patch you wish to apply should - be saved into a file named + 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> + + <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen> + + <para>Patches are + saved into files named <filename>patch-*</filename> where <replaceable>*</replaceable> indicates the pathname of the file that is patched, such as <filename>patch-Imakefile</filename> or - <filename>patch-src-config.h</filename>. These files should - be stored in <varname>PATCHDIR</varname> (usually - <filename>files/</filename>, from where they will be + <filename>patch-src-config.h</filename>.</para> + + <para>After the file has been modified, &man.diff.1; is used to + record the differences between the original and the modified + version. <option>-u</option> causes &man.diff.1; to produce + <quote>unified</quote> diffs, the preferred form.</para> + + <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 + 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 your port's + <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, you should avoid - having more than one patch fix the same file (e.g., + 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>). @@ -788,6 +810,13 @@ PLIST_DIRS= lib/X11/oneko</programlistin <filename>patch-ab</filename> etc, always mention the path and file name in patch names.</para> + <para>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 + <filename>.orig</filename> extension, then make modifications. + Then use <command>make makepatch</command> + to write updated patch files to the + <filename>files</filename> directory of the port.</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 @@ -798,23 +827,23 @@ PLIST_DIRS= lib/X11/oneko</programlistin <literal>$RCS</literal>.</para> <para>Using the recurse (<option>-r</option>) option to - &man.diff.1; to generate patches is fine, but please take a - look at the resulting patches to make sure you do not have any + &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, <filename>Makefile</filename>s when the port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and should - be deleted. If you had to edit + be deleted. If it was necessary to edit <filename>configure.in</filename> and run <command>autoconf</command> to regenerate <command>configure</command>, do not take the diffs of <command>configure</command> (it often grows to a few thousand - lines!); define <literal>USE_AUTOTOOLS=autoconf:261</literal> + lines!). Instead, define <literal>USE_AUTOTOOLS=autoconf:261</literal> and take the diffs of <filename>configure.in</filename>.</para> - <para>Also, try to minimize the amount of non-functional - whitespace changes in your patches. It is common in the Open + <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. If you take a working piece of functionality from one project to fix @@ -822,7 +851,7 @@ PLIST_DIRS= lib/X11/oneko</programlistin 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 you + hard to find out what exactly caused the problem and what was changed at all.</para> <para>If you had to delete a file, then you can do it in the @@ -865,13 +894,6 @@ DOS2UNIX_REGEX= .*\.([ch]|cpp)</programl <programlisting>USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> - - <para>If you want to create a patch file based off of an - existing file, you can copy it with an - <filename>.orig</filename> extension, and then modify the - original one. The <buildtarget>makepatch</buildtarget> target - will write out an appropriate patch file to the - <filename>files</filename> directory of the port.</para> </sect1> <sect1 xml:id="slow-configure">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402061649.s16Gnoc7024240>