os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes, translators please ignore.

Browse source
This commit is contained in:
Warren Block 2014-02-16 02:39:13 +00:00
parent 65a4d09af1
commit a7527eca9c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43954
1 changed files with 348 additions and 361 deletions
Download patch file Download diff file Expand all files Collapse all files

709
en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml
View file

@ -4,427 +4,414 @@
$FreeBSD$ $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> <title>Slow Porting</title>
<para>Okay, so it was not that simple, and the port required some <para>Okay, so it was not that simple, and the port required some
modifications to get it to work. In this section, we will 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 explain, step by step, how to modify it to get it to work with the
the ports paradigm.</para> ports paradigm.</para>
<sect1 xml:id="slow-work"> <sect1 xml:id="slow-work">
<title>How Things Work</title> <title>How Things Work</title>
<para>First, this is the sequence of events which occurs when <para>First, this is the sequence of events which occurs when the
the user first types <command>make</command> in your port's user first types <command>make</command> in your port's
directory. You may find that having directory. You may find that having
<filename>bsd.port.mk</filename> in another window while you <filename>bsd.port.mk</filename> in another window while you
read this really helps to understand it.</para> read this really helps to understand it.</para>
<para>But do not worry if you do not really understand what <para>But do not worry if you do not really understand what
<filename>bsd.port.mk</filename> is doing, not many people <filename>bsd.port.mk</filename> is doing, not many people do...
do... <!-- smiley --><emphasis>:-)</emphasis></para> <!-- smiley --><emphasis>:-)</emphasis></para>
<procedure> <procedure>
<step> <step>
<para>The <buildtarget>fetch</buildtarget> target is run. <para>The <buildtarget>fetch</buildtarget> target is run. The
The <buildtarget>fetch</buildtarget> target is responsible <buildtarget>fetch</buildtarget> target is responsible for
for making sure that the tarball exists locally in making sure that the tarball exists locally in
<varname>DISTDIR</varname>. If <varname>DISTDIR</varname>. If
<buildtarget>fetch</buildtarget> cannot find the required <buildtarget>fetch</buildtarget> cannot find the required
files in <varname>DISTDIR</varname> it will look up the files in <varname>DISTDIR</varname> it will look up the URL
URL <varname>MASTER_SITES</varname>, which is set in the <varname>MASTER_SITES</varname>, which is set in the
Makefile, as well as our FTP mirrors where we put Makefile, as well as our FTP mirrors where we put distfiles
distfiles as backup. It will then attempt to fetch the as backup. It will then attempt to fetch the named
named distribution file with <varname>FETCH</varname>, distribution file with <varname>FETCH</varname>, assuming
assuming that the requesting site has direct access to the that the requesting site has direct access to the Internet.
Internet. If that succeeds, it will save the file in If that succeeds, it will save the file in
<varname>DISTDIR</varname> for future use and <varname>DISTDIR</varname> for future use and
proceed.</para> proceed.</para>
</step> </step>
<step> <step>
<para>The <buildtarget>extract</buildtarget> target is run. <para>The <buildtarget>extract</buildtarget> target is run.
It looks for your port's distribution file (typically a It looks for your port's distribution file (typically a
<command>gzip</command>ped tarball) in <command>gzip</command>ped tarball) in
<varname>DISTDIR</varname> and unpacks it into a temporary <varname>DISTDIR</varname> and unpacks it into a temporary
subdirectory specified by <varname>WRKDIR</varname> subdirectory specified by <varname>WRKDIR</varname>
(defaults to <filename>work</filename>).</para> (defaults to <filename>work</filename>).</para>
</step> </step>
<step> <step>
<para>The <buildtarget>patch</buildtarget> target is run. <para>The <buildtarget>patch</buildtarget> target is run.
First, any patches defined in First, any patches defined in <varname>PATCHFILES</varname>
<varname>PATCHFILES</varname> are applied. Second, if any are applied. Second, if any patch files named
patch files named <filename>patch-*</filename> are found in
<filename>patch-*</filename> <varname>PATCHDIR</varname> (defaults to the
are found in <varname>PATCHDIR</varname> (defaults to the <filename>files</filename> subdirectory), they are applied
<filename>files</filename> subdirectory), they are applied at this time in alphabetical order.</para>
at this time in alphabetical order.</para> </step>
</step>
<step> <step>
<para>The <buildtarget>configure</buildtarget> target is <para>The <buildtarget>configure</buildtarget> target is run.
run. This can do any one of many different things.</para> This can do any one of many different things.</para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>If it exists, <para>If it exists, <filename>scripts/configure</filename>
<filename>scripts/configure</filename> is run.</para> is run.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If <varname>HAS_CONFIGURE</varname> or <para>If <varname>HAS_CONFIGURE</varname> or
<varname>GNU_CONFIGURE</varname> is set, <varname>GNU_CONFIGURE</varname> is set,
<filename>WRKSRC/configure</filename> <filename>WRKSRC/configure</filename> is run.</para>
is run.</para> </listitem>
</listitem> </orderedlist>
</step>
</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> <step>
<para>The <buildtarget>build</buildtarget> target is run. <para>The <buildtarget>stage</buildtarget> target is run.
This is responsible for descending into the port's private This puts the final set of built files into a temporary
working directory (<varname>WRKSRC</varname>) and building directory (<varname>STAGEDIR</varname>, see
it.</para> <xref linkend="staging"/>). The hierarchy of this directory
</step> mirrors that of the system on which the package will be
installed.</para>
</step>
<step> <step>
<para>The <buildtarget>stage</buildtarget> target is run. <para>The <buildtarget>install</buildtarget> target is run.
This puts the final set of built files into a temporary This copies the files listed in the port's pkg-plist to the
directory (<varname>STAGEDIR</varname>, see host system.</para>
<xref linkend="staging"/>). The hierarchy of this </step>
directory mirrors that of the system on which the package </procedure>
will be installed.</para>
</step>
<step> <para>The above are the default actions. In addition, you can
<para>The <buildtarget>install</buildtarget> target is run. define targets
This copies the files listed in the port's pkg-plist to <buildtarget>pre-<replaceable>something</replaceable></buildtarget>
the host system.</para> or
</step> <buildtarget>post-<replaceable>something</replaceable></buildtarget>,
</procedure> 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>The above are the default actions. In addition, you can <para>For example, if you have a
define targets <buildtarget>post-extract</buildtarget> target defined in your
<buildtarget>pre-<replaceable>something</replaceable></buildtarget> <filename>Makefile</filename>, and a file
or <filename>pre-build</filename> in the
<buildtarget>post-<replaceable>something</replaceable></buildtarget>, <filename>scripts</filename> subdirectory, the
or put scripts with those names, in the <buildtarget>post-extract</buildtarget> target will be called
<filename>scripts</filename> subdirectory, and they will be after the regular extraction actions, and the
run before or after the default actions are done.</para> <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>For example, if you have a <para>The default actions are done by the
<buildtarget>post-extract</buildtarget> target defined in your <filename>bsd.port.mk</filename> targets
<filename>Makefile</filename>, and a file <buildtarget>do-<replaceable>something</replaceable></buildtarget>.
<filename>pre-build</filename> in the For example, the commands to extract a port are in the target
<filename>scripts</filename> subdirectory, the <buildtarget>do-extract</buildtarget>. If you are not happy
<buildtarget>post-extract</buildtarget> target will be called with the default target, you can fix it by redefining the
after the regular extraction actions, and the <buildtarget>do-<replaceable>something</replaceable></buildtarget>
<filename>pre-build</filename> script will be executed before target in your <filename>Makefile</filename>.</para>
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 <note>
<filename>bsd.port.mk</filename> targets <para>The <quote>main</quote> targets (e.g.,
<buildtarget>do-<replaceable>something</replaceable></buildtarget>. <buildtarget>extract</buildtarget>,
For example, the commands to extract a port are in the target <buildtarget>configure</buildtarget>, etc.) do nothing more
<buildtarget>do-extract</buildtarget>. If you are not happy than make sure all the stages up to that one are completed and
with the default target, you can fix it by redefining the call the real targets or scripts, and they are not intended to
<buildtarget>do-<replaceable>something</replaceable></buildtarget> be changed. If you want to fix the extraction, fix
target in your <filename>Makefile</filename>.</para> <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>
<note> <para>Now that you understand what goes on when the user types
<para>The <quote>main</quote> targets (e.g., <command>make install</command>, let us go through the
<buildtarget>extract</buildtarget>, recommended steps to create the perfect port.</para>
<buildtarget>configure</buildtarget>, etc.) do nothing more </sect1>
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 <sect1 xml:id="slow-sources">
<command>make install</command>, let <title>Getting the Original Sources</title>
us go through the recommended steps to create the perfect
port.</para>
</sect1>
<sect1 xml:id="slow-sources"> <para>Get the original sources (normally) as a compressed tarball
<title>Getting the Original Sources</title> (<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>Get the original sources (normally) as a compressed <para>You will need to set the variable
tarball <varname>MASTER_SITES</varname> to reflect where the original
(<filename>foo.tar.gz</filename> or tarball resides. You will find convenient shorthand definitions
<filename>foo.tar.bz2</filename>) for most mainstream sites in <filename>bsd.sites.mk</filename>.
and copy it into <varname>DISTDIR</varname>. Always use Please use these sites&mdash;and the associated
<emphasis>mainstream</emphasis> sources when and where you definitions&mdash;if at all possible, to help avoid the problem
can.</para> 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>You will need to set the variable <para>If you cannot find a FTP/HTTP site that is well-connected to
<varname>MASTER_SITES</varname> to reflect where the original the net, or can only find sites that have irritatingly
tarball resides. You will find convenient shorthand non-standard formats, you might want to put a copy on a reliable
definitions for most mainstream sites in FTP or HTTP server that you control (e.g., your home
<filename>bsd.sites.mk</filename>. Please use these page).</para>
sites&mdash;and the associated definitions&mdash;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 <para>If you cannot find somewhere convenient and reliable to put
to the net, or can only find sites that have irritatingly the distfile we can <quote>house</quote> it ourselves on
non-standard formats, you might want to put a copy on a <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the
reliable FTP or HTTP server that you control (e.g., your home least-preferred solution. The distfile must be placed into
page).</para> <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 you cannot find somewhere convenient and reliable to <para>If your port's distfile changes all the time without any
put the distfile we can <quote>house</quote> it ourselves on kind of version update by the author, consider putting the
<systemitem>ftp.FreeBSD.org</systemitem>; however, this is the distfile on your home page and listing it as the first
least-preferred solution. The distfile must be placed into <varname>MASTER_SITES</varname>. If you can, try to talk the
<filename>~/public_distfiles/</filename> of someone's port author out of doing this; it really does help to establish
<systemitem>freefall</systemitem> account. Ask the person who some kind of source code control. Hosting your own version will
commits your port to do this. This person will also set prevent users from getting
<varname>MASTER_SITES</varname> to <errorname>checksum mismatch</errorname> errors, and also reduce
<varname>MASTER_SITE_LOCAL</varname> and the workload of maintainers of our FTP site. Also, if there is
<varname>MASTER_SITE_SUBDIR</varname> to their only one master site for the port, it is recommended that you
<systemitem>freefall</systemitem> username.</para> house a backup at your site and list it as the second
<varname>MASTER_SITES</varname>.</para>
<para>If your port's distfile changes all the time without any <para>If your port requires some additional `patches' that are
kind of version update by the author, consider putting the available on the Internet, fetch them too and put them in
distfile on your home page and listing it as the first <varname>DISTDIR</varname>. Do not worry if they come from a
<varname>MASTER_SITES</varname>. If you can, try to talk the site other than where you got the main source tarball, we have a
port author out of doing this; it really does help to way to handle these situations (see the description of <link
establish some kind of source code control. Hosting your own linkend="porting-patchfiles">PATCHFILES</link> below).</para>
version will prevent users from getting </sect1>
<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 <sect1 xml:id="slow-modifying">
available on the Internet, fetch them too and put them in <title>Modifying the Port</title>
<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"> <para>Unpack a copy of the tarball in a private directory and make
<title>Modifying the Port</title> 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>Unpack a copy of the tarball in a private directory and <para>If your port requires significant user
make whatever changes are necessary to get the port to compile interaction/customization to compile or install, you should take
properly under the current version of &os;. Keep a look at one of Larry Wall's classic
<emphasis>careful track</emphasis> of everything you do, as <application>Configure</application> scripts and perhaps do
you will be automating the process shortly. Everything, something similar yourself. The goal of the new ports
including the deletion, addition, or modification of files collection is to make each port as <quote>plug-and-play</quote>
should be doable using an automated script or patch file when as possible for the end-user while using a minimum of disk
your port is finished.</para> space.</para>
<para>If your port requires significant user <note>
interaction/customization to compile or install, you should <para>Unless explicitly stated, patch files, scripts, and other
take a look at one of Larry Wall's classic files you have created and contributed to the &os; ports
<application>Configure</application> scripts and perhaps do collection are assumed to be covered by the standard BSD
something similar yourself. The goal of the new ports copyright conditions.</para>
collection is to make each port as </note>
<quote>plug-and-play</quote> as possible for the end-user </sect1>
while using a minimum of disk space.</para>
<note> <sect1 xml:id="slow-patch">
<para>Unless explicitly stated, patch files, scripts, and <title>Patching</title>
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"> <para>In the preparation of the port, files that have been added
<title>Patching</title> 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>
<para>In the preparation of the port, files that have been added <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
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>Patches are saved into files named <para>After the file has been modified, &man.diff.1; is used to
<filename>patch-*</filename> where record the differences between the original and the modified
<replaceable>*</replaceable> indicates the pathname of the version. <option>-u</option> causes &man.diff.1; to produce
file that is patched, such as <quote>unified</quote> diffs, the preferred form.</para>
<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 <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> &gt; patch-<replaceable>pathname-file</replaceable></userinput></screen>
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> &gt; 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>
<para>When generating patches for new, added files, <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> &gt; patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
<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> &gt; 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>Patch files are stored in <varname>PATCHDIR</varname> <para>Please only use characters
(usually <filename class="directory">files/</filename>, from <literal>[-+._a-zA-Z0-9]</literal> for naming patches. Do not
where they will be automatically applied. All patches must be use any other characters besides them. Do not name patches like
relative to <varname>WRKSRC</varname> (generally the directory <filename>patch-aa</filename> or <filename>patch-ab</filename>,
the port's tarball unpacks itself into, that being where the always mention the path and file name in patch names.</para>
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 <para>There is an alternate, easier method for creating patches to
<literal>[-+._a-zA-Z0-9]</literal> for naming patches. Do not existing files. The first steps are the same, make a copy of
use any other characters besides them. Do not name patches the unmodified file with an <filename>.orig</filename>
like <filename>patch-aa</filename> or extension, then make modifications. Then use
<filename>patch-ab</filename>, always mention the path and <command>make makepatch</command> to write updated patch files
file name in patch names.</para> to the <filename>files</filename> directory of the port.</para>
<para>There is an alternate, easier method for creating patches <para>Do not put RCS strings in patches.
to existing files. The first steps are the same, make a copy <application>Subversion</application> will mangle them when we
of the unmodified file with an <filename>.orig</filename> put the files into the ports tree, and when we check them out
extension, then make modifications. Then use again, they will come out different and the patch will fail.
<command>make makepatch</command> to write updated patch files RCS strings are surrounded by dollar
to the <filename>files</filename> directory of the (<literal>&dollar;</literal>) signs, and typically start with
port.</para> <literal>&dollar;Id</literal> or
<literal>&dollar;RCS</literal>.</para>
<para>Do not put RCS strings in patches. <para>Using the recurse (<option>-r</option>) option to
<application>Subversion</application> will mangle them when we &man.diff.1; to generate patches is fine, but please look at the
put the files into the ports tree, and when we check them out resulting patches to make sure there is no unnecessary junk in
again, they will come out different and the patch will fail. there. In particular, diffs between two backup files,
RCS strings are surrounded by dollar <filename>Makefile</filename>s when the port uses
(<literal>&dollar;</literal>) signs, and typically start with <command>Imake</command> or GNU <command>configure</command>,
<literal>&dollar;Id</literal> or etc., are unnecessary and should be deleted. If it was
<literal>&dollar;RCS</literal>.</para> 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>Using the recurse (<option>-r</option>) option to <para>Try to minimize the amount of non-functional whitespace
&man.diff.1; to generate patches is fine, but please changes in patches. It is common in the Open Source world for
look at the resulting patches to make sure there is no projects to share large amounts of a code base, but obey
unnecessary junk in there. In particular, diffs between two different style and indenting rules. When taking a working
backup files, <filename>Makefile</filename>s when the port piece of functionality from one project to fix similar areas in
uses <command>Imake</command> or GNU another, please be careful: the resulting line patch may be full
<command>configure</command>, etc., are unnecessary and should of non-functional changes. It not only increases the size of
be deleted. If it was necessary to edit the <application>Subversion</application> repository but makes
<filename>configure.in</filename> and run it hard to find out what exactly caused the problem and what was
<command>autoconf</command> to regenerate changed at all.</para>
<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 <para>If a file must be deleted, do it in the
changes in patches. It is common in the Open Source world for <buildtarget>post-extract</buildtarget> target rather than as
projects to share large amounts of a code base, but obey part of the patch.</para>
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 <para>Simple replacements can be performed directly from the port
<buildtarget>post-extract</buildtarget> target rather than as <filename>Makefile</filename> using the in-place mode of
part of the patch.</para> &man.sed.1;. This is useful when changes use the value of a
variable:</para>
<para>Simple replacements can be performed directly from the <programlisting>post-patch:
port <filename>Makefile</filename> using the in-place mode of @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
&man.sed.1;. This is useful when changes use the value of a
variable:</para>
<programlisting>post-patch: <para>Quite often, software being ported uses the CR/LF convention
@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting> 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 <programlisting>USES= dos2unix</programlisting>
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> <para>A list of specific files to convert can be given:</para>
<para>A list of specific files to convert can <programlisting>USES= dos2unix
be given:</para>
<programlisting>USES= dos2unix
DOS2UNIX_FILES= util.c util.h</programlisting> DOS2UNIX_FILES= util.c util.h</programlisting>
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
of files across subdirectories. Its argument is a files across subdirectories. Its argument is a
&man.find.1;-compatible regular expression. More on the &man.find.1;-compatible regular expression. More on the format
format is in &man.re.format.7;. This option is useful for is in &man.re.format.7;. This option is useful for converting
converting all files of a given extension. For example, all files of a given extension. For example, convert all source
convert all source code files, leaving binary files code files, leaving binary files intact:</para>
intact:</para>
<programlisting>USES= dos2unix <programlisting>USES= dos2unix
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting> DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>, <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
which invokes <command>find</command> for each element listed invokes <command>find</command> for each element listed in
in it.</para> it.</para>
<programlisting>USES= dos2unix <programlisting>USES= dos2unix
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
</sect1> </sect1>
<sect1 xml:id="slow-configure"> <sect1 xml:id="slow-configure">
<title>Configuring</title> <title>Configuring</title>
<para>Include any additional customization commands in your <para>Include any additional customization commands in your
<filename>configure</filename> script and save it in the <filename>configure</filename> script and save it in the
<filename>scripts</filename> subdirectory. As mentioned <filename>scripts</filename> subdirectory. As mentioned above,
above, you can also do this with <filename>Makefile</filename> you can also do this with <filename>Makefile</filename> targets
targets and/or scripts with the name and/or scripts with the name <filename>pre-configure</filename>
<filename>pre-configure</filename> or or <filename>post-configure</filename>.</para>
<filename>post-configure</filename>.</para> </sect1>
</sect1>
<sect1 xml:id="slow-user-input"> <sect1 xml:id="slow-user-input">
<title>Handling User Input</title> <title>Handling User Input</title>
<para>If your port requires user input to build, configure, or <para>If your port requires user input to build, configure, or
install, you must set <varname>IS_INTERACTIVE</varname> in install, you must set <varname>IS_INTERACTIVE</varname> in your
your <filename>Makefile</filename>. This will allow <filename>Makefile</filename>. This will allow
<quote>overnight builds</quote> to skip your port if the user <quote>overnight builds</quote> to skip your port if the user
sets the variable <envar>BATCH</envar> in his environment (and sets the variable <envar>BATCH</envar> in his environment (and
if the user sets the variable <envar>INTERACTIVE</envar>, then if the user sets the variable <envar>INTERACTIVE</envar>, then
<emphasis>only</emphasis> those ports requiring interaction <emphasis>only</emphasis> those ports requiring interaction are
are built). This will save a lot of wasted time on the set of built). This will save a lot of wasted time on the set of
machines that continually build ports (see below).</para> 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>
<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>