svn commit: r43805 - head/en_US.ISO8859-1/books/porters-handbook
Warren Block
wblock at FreeBSD.org
Thu Feb 6 16:49:51 UTC 2014
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 at 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">
More information about the svn-doc-all
mailing list