os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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

Browse source 
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
1 changed files with 45 additions and 23 deletions

68
en_US.ISO8859-1/books/porters-handbook/book.xml
View file

@ -756,21 +756,43 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<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> &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
<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</programlisting>
<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</programlisting>
<literal>&dollar;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</programlisting>
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)</programlisting>
<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">