Update the slow-porting chapter.
Sponsored by: Absolight
This commit is contained in:
Mathieu Arnold
parent
8f12aa5727
commit
f80b8a1073
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44129
1 changed files with 133 additions and 104 deletions
|
|
@ -99,10 +99,19 @@
|
|||
installed.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>The <buildtarget>package</buildtarget> target is run.
|
||||
This creates a package using the files from the temporary
|
||||
directory created during the
|
||||
<buildtarget>stage</buildtarget> target and the port's
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>The <buildtarget>install</buildtarget> target is run.
|
||||
This copies the files listed in the port's pkg-plist to the
|
||||
host system.</para>
|
||||
This install the package created during the
|
||||
<buildtarget>package</buildtarget> target into the host
|
||||
system.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
|
|
@ -255,133 +264,153 @@
|
|||
|
||||
<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>.</para>
|
||||
<sect2>
|
||||
<title>Automatic Patch Generation</title>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen>
|
||||
</sect2>
|
||||
|
||||
<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>
|
||||
<sect2>
|
||||
<title>Manual Patch Generation</title>
|
||||
|
||||
<screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></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>.</para>
|
||||
|
||||
<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 if the path of
|
||||
a patched file contains an underscore (<literal>_</literal>)
|
||||
character, the patch needs to have two underscores instead in
|
||||
its name. 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>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>
|
||||
|
||||
<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>
|
||||
<screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen>
|
||||
|
||||
<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>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>
|
||||
|
||||
<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>
|
||||
<screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
|
||||
|
||||
<para>Using the recurse (<option>-r</option>) option to
|
||||
&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 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!). Instead, define
|
||||
<literal>USE_AUTOTOOLS=autoconf:261</literal> and take the diffs
|
||||
of <filename>configure.in</filename>.</para>
|
||||
<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>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>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>If a file must be deleted, do it in the
|
||||
<buildtarget>post-extract</buildtarget> target rather than as
|
||||
part of the patch.</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>Simple replacements can be performed directly from the port
|
||||
<filename>Makefile</filename> using the in-place mode of
|
||||
&man.sed.1;. This is useful when changes use the value of a
|
||||
variable:</para>
|
||||
<para>Using the recurse (<option>-r</option>) option to
|
||||
&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 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!). Instead, define
|
||||
<literal>USE_AUTOTOOLS=autoconf:261</literal> and take the
|
||||
diffs of <filename>configure.in</filename>.</para>
|
||||
|
||||
<programlisting>post-patch:
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<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>
|
||||
<title>Simple Automatic Replacements</title>
|
||||
|
||||
<para>Simple replacements can be performed directly from the
|
||||
port <filename>Makefile</filename> using the in-place mode of
|
||||
&man.sed.1;. This is useful when changes use the value of a
|
||||
variable:</para>
|
||||
|
||||
<programlisting>post-patch:
|
||||
@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
|
||||
|
||||
<para>Quite often, software being ported uses the CR/LF convention
|
||||
in source files. This may cause problems with further patching,
|
||||
compiler warnings, or script execution (like
|
||||
<literal>/bin/sh^M not found</literal>.) To quickly convert all
|
||||
files from CR/LF to just LF, add this entry to the port
|
||||
<filename>Makefile</filename>:</para>
|
||||
<para>Quite often, software being ported uses the CR/LF
|
||||
convention in source files. This may cause problems with
|
||||
further patching, compiler warnings, or script execution (like
|
||||
<literal>/bin/sh^M not found</literal>.) To quickly convert
|
||||
all files from CR/LF to just LF, add this entry to the port
|
||||
<filename>Makefile</filename>:</para>
|
||||
|
||||
<programlisting>USES= dos2unix</programlisting>
|
||||
<programlisting>USES= dos2unix</programlisting>
|
||||
|
||||
<para>A list of specific files to convert can be given:</para>
|
||||
<para>A list of specific files to convert can be given:</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_FILES= util.c util.h</programlisting>
|
||||
|
||||
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
|
||||
files across subdirectories. Its argument is a
|
||||
&man.find.1;-compatible regular expression. More on the format
|
||||
is in &man.re.format.7;. This option is useful for converting
|
||||
all files of a given extension. For example, convert all source
|
||||
code files, leaving binary files intact:</para>
|
||||
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
|
||||
of files across subdirectories. Its argument is a
|
||||
&man.find.1;-compatible regular expression. More on the
|
||||
format is in &man.re.format.7;. This option is useful for
|
||||
converting all files of a given extension. For example,
|
||||
convert all source code files, leaving binary files
|
||||
intact:</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
|
||||
|
||||
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
|
||||
invokes <command>find</command> for each element listed in
|
||||
it.</para>
|
||||
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
|
||||
which invokes <command>find</command> for each element listed
|
||||
in it.</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="slow-configure">
|
||||
|
|
|
|||
Loading…
Reference in a new issue