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

igor -Ry and some other rewording and fixes.

Browse source 
Differential Revision:	https://reviews.freebsd.org/D652
Reviewed by:	wblock
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-09-10 12:56:21 +00:00
parent 1e8a353c1f
commit 7851544219
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45585
1 changed files with 59 additions and 58 deletions

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

@ -19,13 +19,13 @@
<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>
user first types <command>make</command> in the port's
directory. Having
<filename>bsd.port.mk</filename> in another window while
reading 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...
<para>But do not worry not many people understand exactly how
<filename>bsd.port.mk</filename> is working...
<!-- smiley --><emphasis>:-)</emphasis></para>
<procedure>
@ -48,7 +48,7 @@
<step>
<para>The <buildtarget>extract</buildtarget> target is run.
It looks for your port's distribution file (typically a
It looks for the 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>
@ -115,7 +115,7 @@
</step>
</procedure>
<para>The above are the default actions. In addition, you can
<para>The above are the default actions. In addition,
define targets
<buildtarget>pre-<replaceable>something</replaceable></buildtarget>
or
@ -124,35 +124,35 @@
<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
<para>For example, if there is a
<buildtarget>post-extract</buildtarget> target defined in the
<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
after the regular extraction actions, and
<filename>pre-build</filename> will be executed before
the default build rules are done. It is recommended to
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>
targets from <filename>bsd.port.mk</filename>.
For example, the commands to extract a port are in the target
<buildtarget>do-extract</buildtarget>. If
the default target does not do the job right, redefine the
<buildtarget>do-<replaceable>something</replaceable></buildtarget>
target in the <filename>Makefile</filename>.</para>
<note>
<para>The <quote>main</quote> targets (e.g.,
<para>The <quote>main</quote> targets (for example,
<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
be changed. to fix the extraction, fix
<buildtarget>do-extract</buildtarget>, but never ever change
the way <buildtarget>extract</buildtarget> operates!
Additionally, the target
@ -160,8 +160,8 @@
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
<para>Now that what goes on when the user types <command>make
install</command> is better understood, let us go through the
recommended steps to create the perfect port.</para>
</sect1>
@ -172,54 +172,55 @@
(<filename>foo.tar.gz</filename> or
<filename><replaceable>foo</replaceable>.tar.bz2</filename>) and
copy it into <varname>DISTDIR</varname>. Always use
<emphasis>mainstream</emphasis> sources when and where you
can.</para>
<emphasis>mainstream</emphasis> sources when and where
possible.</para>
<para>You will need to set the variable
<para>Set the variable
<varname>MASTER_SITES</varname> to reflect where the original
tarball resides. You will find convenient shorthand definitions
tarball resides. Shorthand definitions exist
for most mainstream sites in <filename>bsd.sites.mk</filename>.
Please use these 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>
becomes a maintenance nightmare for everyone involved. See
<xref linkend="makefile-master_sites"/> for details.</para>
<para>If you cannot find a FTP/HTTP site that is well-connected to
<para>If there is no 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
non-standard formats, put a copy on a reliable
FTP or HTTP server (for example, a home
page).</para>
<para>If you cannot find somewhere convenient and reliable to put
the distfile we can <quote>house</quote> it ourselves on
<para>If a convenient and reliable place to put
the distfile cannot be found, 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
commits the 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
<para>If the 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
distfile on a home page and listing it as the first
<varname>MASTER_SITES</varname>. 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
some kind of source code control. Hosting a specific 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
only one master site for the port, it is recommended to
house a backup on a home page and list it as the second
<varname>MASTER_SITES</varname>.</para>
<para>If your port requires some additional `patches' that are
<para>If the 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
site other than where the main source tarball comes, we have a
way to handle these situations (see the description of <link
linkend="porting-patchfiles">PATCHFILES</link> below).</para>
</sect1>
@ -230,24 +231,24 @@
<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
<emphasis>careful track</emphasis> of steps, as they will be
needed to automate the process shortly. Everything, including
the deletion, addition, or modification of files has to be
doable using an automated script or patch file when the port is
finished.</para>
<para>If your port requires significant user
interaction/customization to compile or install, you should take
<para>If the port requires significant user
interaction/customization to compile or install, 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
something similar. 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
files created and contributed to the &os; ports
collection are assumed to be covered by the standard BSD
copyright conditions.</para>
</note>
@ -385,7 +386,7 @@
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
etc., are unnecessary and have to 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
@ -444,10 +445,10 @@ DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
<sect1 xml:id="slow-configure">
<title>Configuring</title>
<para>Include any additional customization commands in your
<para>Include any additional customization commands in the
<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
it is also possible do this with <filename>Makefile</filename> targets
and/or scripts with the name <filename>pre-configure</filename>
or <filename>post-configure</filename>.</para>
</sect1>
@ -455,10 +456,10 @@ DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
<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
<para>If the port requires user input to build, configure, or
install, set <varname>IS_INTERACTIVE</varname> in the
<filename>Makefile</filename>. This will allow
<quote>overnight builds</quote> to skip your port if the user
<quote>overnight builds</quote> to skip it. 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
@ -466,8 +467,8 @@ DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
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
answers to the questions,
<varname>PACKAGE_BUILDING</varname> be used to turn off the
interactive script when it is set. This will allow us to build
the packages for CDROMs and FTP.</para>
</sect1>