svn commit: r44129 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting
Mathieu Arnold
mat at FreeBSD.org
Wed Mar 5 15:23:52 UTC 2014
Author: mat (ports committer)
Date: Wed Mar 5 15:23:51 2014
New Revision: 44129
URL: http://svnweb.freebsd.org/changeset/doc/44129
Log:
Update the slow-porting chapter.
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Wed Mar 5 14:23:30 2014 (r44128)
+++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Wed Mar 5 15:23:51 2014 (r44129)
@@ -100,9 +100,18 @@
</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>
-
- <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> > 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> > 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 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
- <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
- 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
- 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
- &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>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>
-
- <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>
+ <sect2>
+ <title>Automatic Patch Generation</title>
+
+ <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>
+
+ <sect2>
+ <title>Manual Patch Generation</title>
+
+ <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>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> > 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> > 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>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>
+
+ </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:
+ <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">
More information about the svn-doc-all
mailing list