Date: Sun, 16 Feb 2014 02:39:13 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43954 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting Message-ID: <201402160239.s1G2dDF0052951@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Feb 16 02:39:13 2014 New Revision: 43954 URL: http://svnweb.freebsd.org/changeset/doc/43954 Log: Whitespace-only fixes, translators please ignore. 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 Sun Feb 16 02:24:38 2014 (r43953) +++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml Sun Feb 16 02:39:13 2014 (r43954) @@ -4,427 +4,414 @@ $FreeBSD$ --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="slow-porting"> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="slow-porting"> + + <title>Slow Porting</title> + + <para>Okay, so it was not that simple, and the port required some + modifications to get it to work. In this section, we will + explain, step by step, how to modify it to get it to work with the + ports paradigm.</para> + + <sect1 xml:id="slow-work"> + <title>How Things Work</title> + + <para>First, this is the sequence of events which occurs when the + user first types <command>make</command> in your port's + directory. You may find that having + <filename>bsd.port.mk</filename> in another window while you + read this really helps to understand it.</para> + + <para>But do not worry if you do not really understand what + <filename>bsd.port.mk</filename> is doing, not many people do... + <!-- smiley --><emphasis>:-)</emphasis></para> + + <procedure> + <step> + <para>The <buildtarget>fetch</buildtarget> target is run. The + <buildtarget>fetch</buildtarget> target is responsible for + making sure that the tarball exists locally in + <varname>DISTDIR</varname>. If + <buildtarget>fetch</buildtarget> cannot find the required + files in <varname>DISTDIR</varname> it will look up the URL + <varname>MASTER_SITES</varname>, which is set in the + Makefile, as well as our FTP mirrors where we put distfiles + as backup. It will then attempt to fetch the named + distribution file with <varname>FETCH</varname>, assuming + that the requesting site has direct access to the Internet. + If that succeeds, it will save the file in + <varname>DISTDIR</varname> for future use and + proceed.</para> + </step> + + <step> + <para>The <buildtarget>extract</buildtarget> target is run. + It looks for your port's distribution file (typically a + <command>gzip</command>ped tarball) in + <varname>DISTDIR</varname> and unpacks it into a temporary + subdirectory specified by <varname>WRKDIR</varname> + (defaults to <filename>work</filename>).</para> + </step> + + <step> + <para>The <buildtarget>patch</buildtarget> target is run. + First, any patches defined in <varname>PATCHFILES</varname> + are applied. Second, if any patch files named + <filename>patch-*</filename> are found in + <varname>PATCHDIR</varname> (defaults to the + <filename>files</filename> subdirectory), they are applied + at this time in alphabetical order.</para> + </step> + + <step> + <para>The <buildtarget>configure</buildtarget> target is run. + This can do any one of many different things.</para> + + <orderedlist> + <listitem> + <para>If it exists, <filename>scripts/configure</filename> + is run.</para> + </listitem> + + <listitem> + <para>If <varname>HAS_CONFIGURE</varname> or + <varname>GNU_CONFIGURE</varname> is set, + <filename>WRKSRC/configure</filename> is run.</para> + </listitem> + </orderedlist> + </step> + + <step> + <para>The <buildtarget>build</buildtarget> target is run. + This is responsible for descending into the port's private + working directory (<varname>WRKSRC</varname>) and building + it.</para> + </step> + + <step> + <para>The <buildtarget>stage</buildtarget> target is run. + This puts the final set of built files into a temporary + directory (<varname>STAGEDIR</varname>, see + <xref linkend="staging"/>). The hierarchy of this directory + mirrors that of the system on which the package will be + installed.</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> + </step> + </procedure> + + <para>The above are the default actions. In addition, you can + define targets + <buildtarget>pre-<replaceable>something</replaceable></buildtarget> + or + <buildtarget>post-<replaceable>something</replaceable></buildtarget>, + or put scripts with those names, in the + <filename>scripts</filename> subdirectory, and they will be + run before or after the default actions are done.</para> + + <para>For example, if you have a + <buildtarget>post-extract</buildtarget> target defined in your + <filename>Makefile</filename>, and a file + <filename>pre-build</filename> in the + <filename>scripts</filename> subdirectory, the + <buildtarget>post-extract</buildtarget> target will be called + after the regular extraction actions, and the + <filename>pre-build</filename> script will be executed before + the default build rules are done. It is recommended that you + use <filename>Makefile</filename> targets if the actions are + simple enough, because it will be easier for someone to figure + out what kind of non-default action the port requires.</para> + + <para>The default actions are done by the + <filename>bsd.port.mk</filename> targets + <buildtarget>do-<replaceable>something</replaceable></buildtarget>. + For example, the commands to extract a port are in the target + <buildtarget>do-extract</buildtarget>. If you are not happy + with the default target, you can fix it by redefining the + <buildtarget>do-<replaceable>something</replaceable></buildtarget> + target in your <filename>Makefile</filename>.</para> + + <note> + <para>The <quote>main</quote> targets (e.g., + <buildtarget>extract</buildtarget>, + <buildtarget>configure</buildtarget>, etc.) do nothing more + than make sure all the stages up to that one are completed and + call the real targets or scripts, and they are not intended to + be changed. If you want to fix the extraction, fix + <buildtarget>do-extract</buildtarget>, but never ever change + the way <buildtarget>extract</buildtarget> operates! + Additionally, the target + <buildtarget>post-deinstall</buildtarget> is invalid and is + not run by the ports infrastructure.</para> + </note> + + <para>Now that you understand what goes on when the user types + <command>make install</command>, let us go through the + recommended steps to create the perfect port.</para> + </sect1> + + <sect1 xml:id="slow-sources"> + <title>Getting the Original Sources</title> + + <para>Get the original sources (normally) as a compressed tarball + (<filename>foo.tar.gz</filename> or + <filename>foo.tar.bz2</filename>) and copy it into + <varname>DISTDIR</varname>. Always use + <emphasis>mainstream</emphasis> sources when and where you + can.</para> + + <para>You will need to set the variable + <varname>MASTER_SITES</varname> to reflect where the original + tarball resides. You will find convenient shorthand definitions + for most mainstream sites in <filename>bsd.sites.mk</filename>. + Please use these sites—and the associated + definitions—if at all possible, to help avoid the problem + of having the same information repeated over again many times in + the source base. As these sites tend to change over time, this + becomes a maintenance nightmare for everyone involved.</para> + + <para>If you cannot find a FTP/HTTP site that is well-connected to + the net, or can only find sites that have irritatingly + non-standard formats, you might want to put a copy on a reliable + FTP or HTTP server that you control (e.g., your home + page).</para> + + <para>If you cannot find somewhere convenient and reliable to put + the distfile we can <quote>house</quote> it ourselves on + <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the + least-preferred solution. The distfile must be placed into + <filename>~/public_distfiles/</filename> of someone's + <systemitem>freefall</systemitem> account. Ask the person who + commits your port to do this. This person will also set + <varname>MASTER_SITES</varname> to + <varname>MASTER_SITE_LOCAL</varname> and + <varname>MASTER_SITE_SUBDIR</varname> to their + <systemitem>freefall</systemitem> username.</para> + + <para>If your port's distfile changes all the time without any + kind of version update by the author, consider putting the + distfile on your home page and listing it as the first + <varname>MASTER_SITES</varname>. If you can, try to talk the + port author out of doing this; it really does help to establish + some kind of source code control. Hosting your own version will + prevent users from getting + <errorname>checksum mismatch</errorname> errors, and also reduce + the workload of maintainers of our FTP site. Also, if there is + only one master site for the port, it is recommended that you + house a backup at your site and list it as the second + <varname>MASTER_SITES</varname>.</para> + + <para>If your port requires some additional `patches' that are + available on the Internet, fetch them too and put them in + <varname>DISTDIR</varname>. Do not worry if they come from a + site other than where you got the main source tarball, we have a + way to handle these situations (see the description of <link + linkend="porting-patchfiles">PATCHFILES</link> below).</para> + </sect1> + + <sect1 xml:id="slow-modifying"> + <title>Modifying the Port</title> + + <para>Unpack a copy of the tarball in a private directory and make + whatever changes are necessary to get the port to compile + properly under the current version of &os;. Keep + <emphasis>careful track</emphasis> of everything you do, as you + will be automating the process shortly. Everything, including + the deletion, addition, or modification of files should be + doable using an automated script or patch file when your port is + finished.</para> + + <para>If your port requires significant user + interaction/customization to compile or install, you should take + a look at one of Larry Wall's classic + <application>Configure</application> scripts and perhaps do + something similar yourself. The goal of the new ports + collection is to make each port as <quote>plug-and-play</quote> + as possible for the end-user while using a minimum of disk + space.</para> + + <note> + <para>Unless explicitly stated, patch files, scripts, and other + files you have created and contributed to the &os; ports + collection are assumed to be covered by the standard BSD + copyright conditions.</para> + </note> + </sect1> + + <sect1 xml:id="slow-patch"> + <title>Patching</title> + + <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> + + <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> + + <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> - <title>Slow Porting</title> + <programlisting>USES= dos2unix</programlisting> - <para>Okay, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will - explain, step by step, how to modify it to get it to work with - the ports paradigm.</para> - - <sect1 xml:id="slow-work"> - <title>How Things Work</title> - - <para>First, this is the sequence of events which occurs when - the user first types <command>make</command> in your port's - directory. You may find that having - <filename>bsd.port.mk</filename> in another window while you - read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people - do... <!-- smiley --><emphasis>:-)</emphasis></para> - - <procedure> - <step> - <para>The <buildtarget>fetch</buildtarget> target is run. - The <buildtarget>fetch</buildtarget> target is responsible - for making sure that the tarball exists locally in - <varname>DISTDIR</varname>. If - <buildtarget>fetch</buildtarget> cannot find the required - files in <varname>DISTDIR</varname> it will look up the - URL <varname>MASTER_SITES</varname>, which is set in the - Makefile, as well as our FTP mirrors where we put - distfiles as backup. It will then attempt to fetch the - named distribution file with <varname>FETCH</varname>, - assuming that the requesting site has direct access to the - Internet. If that succeeds, it will save the file in - <varname>DISTDIR</varname> for future use and - proceed.</para> - </step> - - <step> - <para>The <buildtarget>extract</buildtarget> target is run. - It looks for your port's distribution file (typically a - <command>gzip</command>ped tarball) in - <varname>DISTDIR</varname> and unpacks it into a temporary - subdirectory specified by <varname>WRKDIR</varname> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <buildtarget>patch</buildtarget> target is run. - First, any patches defined in - <varname>PATCHFILES</varname> are applied. Second, if any - patch files named - <filename>patch-*</filename> - are found in <varname>PATCHDIR</varname> (defaults to the - <filename>files</filename> subdirectory), they are applied - at this time in alphabetical order.</para> - </step> - - <step> - <para>The <buildtarget>configure</buildtarget> target is - run. This can do any one of many different things.</para> - - <orderedlist> - <listitem> - <para>If it exists, - <filename>scripts/configure</filename> is run.</para> - </listitem> - - <listitem> - <para>If <varname>HAS_CONFIGURE</varname> or - <varname>GNU_CONFIGURE</varname> is set, - <filename>WRKSRC/configure</filename> - is run.</para> - </listitem> - - </orderedlist> - </step> - - <step> - <para>The <buildtarget>build</buildtarget> target is run. - This is responsible for descending into the port's private - working directory (<varname>WRKSRC</varname>) and building - it.</para> - </step> - - <step> - <para>The <buildtarget>stage</buildtarget> target is run. - This puts the final set of built files into a temporary - directory (<varname>STAGEDIR</varname>, see - <xref linkend="staging"/>). The hierarchy of this - directory mirrors that of the system on which the package - will be installed.</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> - </step> - </procedure> - - <para>The above are the default actions. In addition, you can - define targets - <buildtarget>pre-<replaceable>something</replaceable></buildtarget> - or - <buildtarget>post-<replaceable>something</replaceable></buildtarget>, - or put scripts with those names, in the - <filename>scripts</filename> subdirectory, and they will be - run before or after the default actions are done.</para> - - <para>For example, if you have a - <buildtarget>post-extract</buildtarget> target defined in your - <filename>Makefile</filename>, and a file - <filename>pre-build</filename> in the - <filename>scripts</filename> subdirectory, the - <buildtarget>post-extract</buildtarget> target will be called - after the regular extraction actions, and the - <filename>pre-build</filename> script will be executed before - the default build rules are done. It is recommended that you - use <filename>Makefile</filename> targets if the actions are - simple enough, because it will be easier for someone to figure - out what kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets - <buildtarget>do-<replaceable>something</replaceable></buildtarget>. - For example, the commands to extract a port are in the target - <buildtarget>do-extract</buildtarget>. If you are not happy - with the default target, you can fix it by redefining the - <buildtarget>do-<replaceable>something</replaceable></buildtarget> - target in your <filename>Makefile</filename>.</para> - - <note> - <para>The <quote>main</quote> targets (e.g., - <buildtarget>extract</buildtarget>, - <buildtarget>configure</buildtarget>, etc.) do nothing more - than make sure all the stages up to that one are completed - and call the real targets or scripts, and they are not - intended to be changed. If you want to fix the extraction, - fix <buildtarget>do-extract</buildtarget>, but never ever - change the way <buildtarget>extract</buildtarget> - operates! Additionally, the target - <buildtarget>post-deinstall</buildtarget> is invalid and - is not run by the ports infrastructure.</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make install</command>, let - us go through the recommended steps to create the perfect - port.</para> - </sect1> - - <sect1 xml:id="slow-sources"> - <title>Getting the Original Sources</title> - - <para>Get the original sources (normally) as a compressed - tarball - (<filename>foo.tar.gz</filename> or - <filename>foo.tar.bz2</filename>) - and copy it into <varname>DISTDIR</varname>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>You will need to set the variable - <varname>MASTER_SITES</varname> to reflect where the original - tarball resides. You will find convenient shorthand - definitions for most mainstream sites in - <filename>bsd.sites.mk</filename>. Please use these - sites—and the associated definitions—if at all - possible, to help avoid the problem of having the same - information repeated over again many times in the source base. - As these sites tend to change over time, this becomes a - maintenance nightmare for everyone involved.</para> - - <para>If you cannot find a FTP/HTTP site that is well-connected - to the net, or can only find sites that have irritatingly - non-standard formats, you might want to put a copy on a - reliable FTP or HTTP server that you control (e.g., your home - page).</para> - - <para>If you cannot find somewhere convenient and reliable to - put the distfile we can <quote>house</quote> it ourselves on - <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the - least-preferred solution. The distfile must be placed into - <filename>~/public_distfiles/</filename> of someone's - <systemitem>freefall</systemitem> account. Ask the person who - commits your port to do this. This person will also set - <varname>MASTER_SITES</varname> to - <varname>MASTER_SITE_LOCAL</varname> and - <varname>MASTER_SITE_SUBDIR</varname> to their - <systemitem>freefall</systemitem> username.</para> - - <para>If your port's distfile changes all the time without any - kind of version update by the author, consider putting the - distfile on your home page and listing it as the first - <varname>MASTER_SITES</varname>. If you can, try to talk the - port author out of doing this; it really does help to - establish some kind of source code control. Hosting your own - version will prevent users from getting - <errorname>checksum mismatch</errorname> errors, and also - reduce the workload of maintainers of our FTP site. Also, if - there is only one master site for the port, it is recommended - that you house a backup at your site and list it as the second - <varname>MASTER_SITES</varname>.</para> - - <para>If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - <varname>DISTDIR</varname>. Do not worry if they come from a - site other than where you got the main source tarball, we have - a way to handle these situations (see the description of - <link linkend="porting-patchfiles">PATCHFILES</link> - below).</para> - </sect1> - - <sect1 xml:id="slow-modifying"> - <title>Modifying the Port</title> - - <para>Unpack a copy of the tarball in a private directory and - make whatever changes are necessary to get the port to compile - properly under the current version of &os;. Keep - <emphasis>careful track</emphasis> of everything you do, as - you will be automating the process shortly. Everything, - including the deletion, addition, or modification of files - should be doable using an automated script or patch file when - your port is finished.</para> - - <para>If your port requires significant user - interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic - <application>Configure</application> scripts and perhaps do - something similar yourself. The goal of the new ports - collection is to make each port as - <quote>plug-and-play</quote> as possible for the end-user - while using a minimum of disk space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and - other files you have created and contributed to the &os; - ports collection are assumed to be covered by the standard - BSD copyright conditions.</para> - </note> - </sect1> - - <sect1 xml:id="slow-patch"> - <title>Patching</title> - - <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> - - <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> - - <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>A list of specific files to convert can be given:</para> - <programlisting>USES= dos2unix</programlisting> - - <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> - </sect1> - - <sect1 xml:id="slow-configure"> - <title>Configuring</title> + </sect1> - <para>Include any additional customization commands in your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned - above, you can also do this with <filename>Makefile</filename> - targets and/or scripts with the name - <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - </sect1> - - <sect1 xml:id="slow-user-input"> - <title>Handling User Input</title> - - <para>If your port requires user input to build, configure, or - install, you must set <varname>IS_INTERACTIVE</varname> in - your <filename>Makefile</filename>. This will allow - <quote>overnight builds</quote> to skip your port if the user - sets the variable <envar>BATCH</envar> in his environment (and - if the user sets the variable <envar>INTERACTIVE</envar>, then - <emphasis>only</emphasis> those ports requiring interaction - are built). This will save a lot of wasted time on the set of - machines that continually build ports (see below).</para> - - <para>It is also recommended that if there are reasonable - default answers to the questions, you check the - <varname>PACKAGE_BUILDING</varname> variable and turn off the - interactive script when it is set. This will allow us to - build the packages for CDROMs and FTP.</para> - </sect1> - </chapter> + <sect1 xml:id="slow-configure"> + <title>Configuring</title> + <para>Include any additional customization commands in your + <filename>configure</filename> script and save it in the + <filename>scripts</filename> subdirectory. As mentioned above, + you can also do this with <filename>Makefile</filename> targets + and/or scripts with the name <filename>pre-configure</filename> + or <filename>post-configure</filename>.</para> + </sect1> + + <sect1 xml:id="slow-user-input"> + <title>Handling User Input</title> + + <para>If your port requires user input to build, configure, or + install, you must set <varname>IS_INTERACTIVE</varname> in your + <filename>Makefile</filename>. This will allow + <quote>overnight builds</quote> to skip your port if the user + sets the variable <envar>BATCH</envar> in his environment (and + if the user sets the variable <envar>INTERACTIVE</envar>, then + <emphasis>only</emphasis> those ports requiring interaction are + built). This will save a lot of wasted time on the set of + machines that continually build ports (see below).</para> + + <para>It is also recommended that if there are reasonable default + answers to the questions, you check the + <varname>PACKAGE_BUILDING</varname> variable and turn off the + interactive script when it is set. This will allow us to build + the packages for CDROMs and FTP.</para> + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402160239.s1G2dDF0052951>