Add examples of using diff(1), move mention of makepatch into that

section.

PR:		docs/186499
Submitted by:	Ondra Knezour <knezour@weboutsourcing.cz>
This commit is contained in:
Warren Block 2014-02-06 16:49:50 +00:00
parent 5fac757ef9
commit 1463965233
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43805

View file

@ -756,21 +756,43 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<title>Patching</title> <title>Patching</title>
<para>In the preparation of the port, files that have been added <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 or changed can be recorded with &man.diff.1; for later
feeding to &man.patch.1;. Each patch you wish to apply should feeding to &man.patch.1;. Doing this with a typical file
be saved into a file named 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 <filename>patch-*</filename> where
<replaceable>*</replaceable> indicates the pathname of the <replaceable>*</replaceable> indicates the pathname of the
file that is patched, such as file that is patched, such as
<filename>patch-Imakefile</filename> or <filename>patch-Imakefile</filename> or
<filename>patch-src-config.h</filename>. These files should <filename>patch-src-config.h</filename>.</para>
be stored in <varname>PATCHDIR</varname> (usually
<filename>files/</filename>, from where they will be <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> &gt; 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> &gt; 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 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 tarball unpacks itself into, that being where the build is
done). To make fixes and upgrades easier, you should avoid done). To make fixes and upgrades easier, avoid
having more than one patch fix the same file (e.g., having more than one patch fix the same file (that is,
<filename>patch-file</filename> and <filename>patch-file</filename> and
<filename>patch-file2</filename> both changing <filename>patch-file2</filename> both changing
<filename>WRKSRC/foobar.c</filename>). <filename>WRKSRC/foobar.c</filename>).
@ -788,6 +810,13 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<filename>patch-ab</filename> etc, always mention the path and <filename>patch-ab</filename> etc, always mention the path and
file name in patch names.</para> 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. <para>Do not put RCS strings in patches.
<application>Subversion</application> will mangle them when we <application>Subversion</application> will mangle them when we
put the files into the ports tree, and when we check them out put the files into the ports tree, and when we check them out
@ -798,23 +827,23 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<literal>&dollar;RCS</literal>.</para> <literal>&dollar;RCS</literal>.</para>
<para>Using the recurse (<option>-r</option>) option to <para>Using the recurse (<option>-r</option>) option to
&man.diff.1; to generate patches is fine, but please take a &man.diff.1; to generate patches is fine, but please
look at the resulting patches to make sure you do not have any look at the resulting patches to make sure there is no
unnecessary junk in there. In particular, diffs between two unnecessary junk in there. In particular, diffs between two
backup files, <filename>Makefile</filename>s when the port backup files, <filename>Makefile</filename>s when the port
uses <command>Imake</command> or GNU uses <command>Imake</command> or GNU
<command>configure</command>, etc., are unnecessary and should <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 <filename>configure.in</filename> and run
<command>autoconf</command> to regenerate <command>autoconf</command> to regenerate
<command>configure</command>, do not take the diffs of <command>configure</command>, do not take the diffs of
<command>configure</command> (it often grows to a few thousand <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 and take the diffs of
<filename>configure.in</filename>.</para> <filename>configure.in</filename>.</para>
<para>Also, try to minimize the amount of non-functional <para>Try to minimize the amount of non-functional
whitespace changes in your patches. It is common in the Open whitespace changes in patches. It is common in the Open
Source world for projects to share large amounts of a code Source world for projects to share large amounts of a code
base, but obey different style and indenting rules. If you base, but obey different style and indenting rules. If you
take a working piece of functionality from one project to fix take a working piece of functionality from one project to fix
@ -822,7 +851,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
line patch may be full of non-functional changes. It not only line patch may be full of non-functional changes. It not only
increases the size of the increases the size of the
<application>Subversion</application> repository but makes it <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> changed at all.</para>
<para>If you had to delete a file, then you can do it in the <para>If you had to delete a file, then you can do it in the
@ -865,13 +894,6 @@ DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
<programlisting>USES= dos2unix <programlisting>USES= dos2unix
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> 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>
<sect1 xml:id="slow-configure"> <sect1 xml:id="slow-configure">