Date: Wed, 5 Mar 2014 15:23:52 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44129 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting Message-ID: <201403051523.s25FNqRh061665@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403051523.s25FNqRh061665>