Whitespace-only fixes, translators please ignore.
This commit is contained in:
Warren Block
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
|
|
@ -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>
|
||||
<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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>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>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>
|
||||
<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>
|
||||
<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>
|
||||
<listitem>
|
||||
<para>If <varname>HAS_CONFIGURE</varname> or
|
||||
<varname>GNU_CONFIGURE</varname> is set,
|
||||
<filename>WRKSRC/configure</filename> is run.</para>
|
||||
</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>
|
||||
<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>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>
|
||||
|
||||
<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>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>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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>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>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 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 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'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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>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>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>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>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>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>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>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>
|
||||
|
||||
<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>
|
||||
|
||||
<programlisting>post-patch:
|
||||
@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
|
||||
<para>Quite often, software being ported uses the CR/LF convention
|
||||
in source files. This may cause problems with further patching,
|
||||
compiler warnings, or script execution (like
|
||||
<literal>/bin/sh^M not found</literal>.) To quickly convert all
|
||||
files from CR/LF to just LF, add this entry to the port
|
||||
<filename>Makefile</filename>:</para>
|
||||
|
||||
<para>Quite often, software being ported uses the CR/LF
|
||||
convention in source files. This may cause problems with
|
||||
further patching, compiler warnings, or script execution (like
|
||||
<literal>/bin/sh^M not found</literal>.) To quickly convert
|
||||
all files from CR/LF to just LF, add this entry to the port
|
||||
<filename>Makefile</filename>:</para>
|
||||
<programlisting>USES= dos2unix</programlisting>
|
||||
|
||||
<programlisting>USES= dos2unix</programlisting>
|
||||
<para>A list of specific files to convert can be given:</para>
|
||||
|
||||
<para>A list of specific files to convert can
|
||||
be given:</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_FILES= util.c util.h</programlisting>
|
||||
|
||||
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
|
||||
of files across subdirectories. Its argument is a
|
||||
&man.find.1;-compatible regular expression. More on the
|
||||
format is in &man.re.format.7;. This option is useful for
|
||||
converting all files of a given extension. For example,
|
||||
convert all source code files, leaving binary files
|
||||
intact:</para>
|
||||
<para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
|
||||
files across subdirectories. Its argument is a
|
||||
&man.find.1;-compatible regular expression. More on the format
|
||||
is in &man.re.format.7;. This option is useful for converting
|
||||
all files of a given extension. For example, convert all source
|
||||
code files, leaving binary files intact:</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
|
||||
|
||||
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
|
||||
which invokes <command>find</command> for each element listed
|
||||
in it.</para>
|
||||
<para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
|
||||
invokes <command>find</command> for each element listed in
|
||||
it.</para>
|
||||
|
||||
<programlisting>USES= dos2unix
|
||||
<programlisting>USES= dos2unix
|
||||
DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
|
||||
</sect1>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="slow-configure">
|
||||
<title>Configuring</title>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue