Reword the patch creation section.
Reviewed by: wblock Sponsored by: Absolight
This commit is contained in:
Mathieu Arnold
parent
b6aa3f6090
commit
cc742fa12f
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=45388
1 changed files with 90 additions and 62 deletions
|
|
@ -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>
|
||||
|
||||
<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>
|
||||
<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>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</programlisting>
|
|||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue