svn commit: r43954 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting
Warren Block
wblock at FreeBSD.org
Sun Feb 16 02:39:13 UTC 2014
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>
More information about the svn-doc-head
mailing list