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>
|
installed.</para>
|
||||||
</step>
|
</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>
|
<step>
|
||||||
<para>The <buildtarget>install</buildtarget> target is run.
|
<para>The <buildtarget>install</buildtarget> target is run.
|
||||||
This copies the files listed in the port's pkg-plist to the
|
This install the package created during the
|
||||||
host system.</para>
|
<buildtarget>package</buildtarget> target into the host
|
||||||
|
system.</para>
|
||||||
</step>
|
</step>
|
||||||
</procedure>
|
</procedure>
|
||||||
|
|
||||||
|
|
@ -255,133 +264,153 @@
|
||||||
|
|
||||||
<screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
|
<screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
|
||||||
|
|
||||||
<para>Patches are saved into files named
|
<sect2>
|
||||||
<filename>patch-*</filename> where <replaceable>*</replaceable>
|
<title>Automatic Patch Generation</title>
|
||||||
indicates the pathname of the file that is patched, such as
|
|
||||||
<filename>patch-Imakefile</filename> or
|
|
||||||
<filename>patch-src-config.h</filename>.</para>
|
|
||||||
|
|
||||||
<para>After the file has been modified, &man.diff.1; is used to
|
<para>When all the files have been modified, use <command>make
|
||||||
record the differences between the original and the modified
|
makepatch</command> from the port directory to write updated
|
||||||
version. <option>-u</option> causes &man.diff.1; to produce
|
patch files to the <filename>files</filename> directory of the
|
||||||
<quote>unified</quote> diffs, the preferred form.</para>
|
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,
|
<sect2>
|
||||||
<option>-N</option> is added to tell &man.diff.1; to treat the
|
<title>Manual Patch Generation</title>
|
||||||
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>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>
|
<para>After the file has been modified, &man.diff.1; is used to
|
||||||
(usually <filename class="directory">files/</filename>, from
|
record the differences between the original and the modified
|
||||||
where they will be automatically applied. All patches must be
|
version. <option>-u</option> causes &man.diff.1; to produce
|
||||||
relative to <varname>WRKSRC</varname> (generally the directory
|
<quote>unified</quote> diffs, the preferred form.</para>
|
||||||
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>Please only use characters
|
<screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen>
|
||||||
<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>There is an alternate, easier method for creating patches to
|
<para>When generating patches for new, added files,
|
||||||
existing files. The first steps are the same, make a copy of
|
<option>-N</option> is added to tell &man.diff.1; to treat the
|
||||||
the unmodified file with an <filename>.orig</filename>
|
non-existent original file as if it existed but was
|
||||||
extension, then make modifications. Then use
|
empty:</para>
|
||||||
<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.
|
<screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
|
||||||
<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>Using the recurse (<option>-r</option>) option to
|
<para>Patch files are stored in <varname>PATCHDIR</varname>
|
||||||
&man.diff.1; to generate patches is fine, but please look at the
|
(usually <filename class="directory">files/</filename>, from
|
||||||
resulting patches to make sure there is no unnecessary junk in
|
where they will be automatically applied. All patches must be
|
||||||
there. In particular, diffs between two backup files,
|
relative to <varname>WRKSRC</varname> (generally the directory
|
||||||
<filename>Makefile</filename>s when the port uses
|
the port's tarball unpacks itself into, that being where the
|
||||||
<command>Imake</command> or GNU <command>configure</command>,
|
build is done). To make fixes and upgrades easier, avoid
|
||||||
etc., are unnecessary and should be deleted. If it was
|
having more than one patch fix the same file (that is,
|
||||||
necessary to edit <filename>configure.in</filename> and run
|
<filename>patch-file</filename> and
|
||||||
<command>autoconf</command> to regenerate
|
<filename>patch-file2</filename> both changing
|
||||||
<command>configure</command>, do not take the diffs of
|
<filename>WRKSRC/foobar.c</filename>). Note that in the path
|
||||||
<command>configure</command> (it often grows to a few thousand
|
of a patched file the <literal>/</literal> are to be replaced
|
||||||
lines!). Instead, define
|
with two underscores <literal>__</literal>. For example, to
|
||||||
<literal>USE_AUTOTOOLS=autoconf:261</literal> and take the diffs
|
patch a file named
|
||||||
of <filename>configure.in</filename>.</para>
|
<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
|
<para>Please only use characters
|
||||||
changes in patches. It is common in the Open Source world for
|
<literal>[-+._a-zA-Z0-9]</literal> for naming patches. Do not
|
||||||
projects to share large amounts of a code base, but obey
|
use any other characters besides them. Do not name patches
|
||||||
different style and indenting rules. When taking a working
|
like <filename>patch-aa</filename> or
|
||||||
piece of functionality from one project to fix similar areas in
|
<filename>patch-ab</filename>, always mention the path and
|
||||||
another, please be careful: the resulting line patch may be full
|
file name in patch names.</para>
|
||||||
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
|
<para>Do not put RCS strings in patches.
|
||||||
<buildtarget>post-extract</buildtarget> target rather than as
|
<application>Subversion</application> will mangle them when we
|
||||||
part of the patch.</para>
|
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
|
<para>Using the recurse (<option>-r</option>) option to
|
||||||
<filename>Makefile</filename> using the in-place mode of
|
&man.diff.1; to generate patches is fine, but please look at
|
||||||
&man.sed.1;. This is useful when changes use the value of a
|
the resulting patches to make sure there is no unnecessary
|
||||||
variable:</para>
|
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>
|
@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
|
||||||
|
|
||||||
<para>Quite often, software being ported uses the CR/LF convention
|
<para>Quite often, software being ported uses the CR/LF
|
||||||
in source files. This may cause problems with further patching,
|
convention in source files. This may cause problems with
|
||||||
compiler warnings, or script execution (like
|
further patching, compiler warnings, or script execution (like
|
||||||
<literal>/bin/sh^M not found</literal>.) To quickly convert all
|
<literal>/bin/sh^M not found</literal>.) To quickly convert
|
||||||
files from CR/LF to just LF, add this entry to the port
|
all files from CR/LF to just LF, add this entry to the port
|
||||||
<filename>Makefile</filename>:</para>
|
<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>
|
DOS2UNIX_FILES= util.c util.h</programlisting>
|
||||||
|
|
||||||
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
|
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
|
||||||
files across subdirectories. Its argument is a
|
of files across subdirectories. Its argument is a
|
||||||
&man.find.1;-compatible regular expression. More on the format
|
&man.find.1;-compatible regular expression. More on the
|
||||||
is in &man.re.format.7;. This option is useful for converting
|
format is in &man.re.format.7;. This option is useful for
|
||||||
all files of a given extension. For example, convert all source
|
converting all files of a given extension. For example,
|
||||||
code files, leaving binary files intact:</para>
|
convert all source code files, leaving binary files
|
||||||
|
intact:</para>
|
||||||
|
|
||||||
<programlisting>USES= dos2unix
|
<programlisting>USES= dos2unix
|
||||||
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
|
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
|
||||||
|
|
||||||
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
|
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
|
||||||
invokes <command>find</command> for each element listed in
|
which invokes <command>find</command> for each element listed
|
||||||
it.</para>
|
in it.</para>
|
||||||
|
|
||||||
<programlisting>USES= dos2unix
|
<programlisting>USES= dos2unix
|
||||||
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
|
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="slow-configure">
|
<sect1 xml:id="slow-configure">
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue