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/D647
Reviewed by:	wblock
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-09-16 12:41:02 +00:00
parent fafa8279b4
commit 50d651dc29
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45618
1 changed files with 106 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

213
en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
View file

@ -17,9 +17,9 @@
<para>Here is a list of common dos and don'ts that are encountered
during the porting process. Check the port against this list,
but also check ports in the <link
xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR
xlink:href="https://bugs.FreeBSD.org/search/">PR
database</link> that others have submitted. Submit any
comments on ports you check as described in <link
comments on ports as described in <link
xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
Reports and General Commentary</link>. Checking ports in the
PR database will both make it faster for us to commit them, and
@ -35,18 +35,18 @@
build (see <link
xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD">
installing ports from a CDROM</link> for an example of
building ports from a read-only tree). If you need to modify
one of the <filename>pkg-<replaceable>*</replaceable></filename>
files, do so by <link linkend="pkg-names">redefining a
variable</link>, not by writing over it.</para>
building ports from a read-only tree). The
<filename>pkg-<replaceable>*</replaceable></filename> files can
be modified by <link linkend="pkg-names">redefining a
variable</link> rather than overwriting the file.</para>
</sect1>
<sect1 xml:id="porting-wrkdirprefix">
<title><varname>WRKDIRPREFIX</varname></title>
<para>Make sure your port honors <varname>WRKDIRPREFIX</varname>.
Most ports do not have to worry about this. In particular, if
you are referring to a <varname>WRKDIR</varname> of another
<para>Make sure the port honors <varname>WRKDIRPREFIX</varname>.
Most ports do not have to worry about this. In particular, when
referring to a <varname>WRKDIR</varname> of another
port, note that the correct location is
<filename>WRKDIRPREFIXPORTSDIR/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
not
@ -55,8 +55,8 @@
<filename>.CURDIR/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
or some such.</para>
<para>Also, if you are defining <varname>WRKDIR</varname>
yourself, make sure you prepend
<para>Also, if defining <varname>WRKDIR</varname>,
make sure to prepend
<literal>&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}</literal> in
the front.</para>
</sect1>
@ -64,7 +64,7 @@
<sect1 xml:id="porting-versions">
<title>Differentiating Operating Systems and OS Versions</title>
<para>You may come across code that needs modifications or
<para>Some code needs modifications or
conditional compilation based upon what version of &os; Unix it
is running under. The preferred way to tell &os; versions apart
are the <literal>__FreeBSD_version</literal> and
@ -87,6 +87,9 @@
/* 9.1+ release specific code here */
# endif
#endif</programlisting>
<para>A complete list of <literal>__FreeBSD_version</literal>
values is available in <xref linkend="versions"/>.</para>
</sect1>
<sect1 xml:id="dads-after-port-mk">
@ -97,15 +100,15 @@
<literal>.include &lt;bsd.port.mk&gt;</literal> line. It
usually can be avoided by including
<filename>bsd.port.pre.mk</filename> somewhere in the middle of
your <filename>Makefile</filename> and
the <filename>Makefile</filename> and
<filename>bsd.port.post.mk</filename> at the end.</para>
<note>
<important>
<para>Include either the
<filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>
pair or <filename>bsd.port.mk</filename> only; do not mix
these two usages.</para>
</note>
</important>
<para><filename>bsd.port.pre.mk</filename> only defines a few
variables, which can be used in tests in the
@ -130,20 +133,20 @@
<row>
<entry><varname>ARCH</varname></entry>
<entry>The architecture as returned by <command>uname
-m</command> (e.g., <literal>i386</literal>)</entry>
-m</command> (for example, <literal>i386</literal>)</entry>
</row>
<row>
<entry><varname>OPSYS</varname></entry>
<entry>The operating system type, as returned by
<command>uname -s</command> (e.g.,
<command>uname -s</command> (for example,
<literal>FreeBSD</literal>)</entry>
</row>
<row>
<entry><varname>OSREL</varname></entry>
<entry>The release version of the operating system
(e.g., <literal>2.1.5</literal> or
(for example, <literal>2.1.5</literal> or
<literal>2.2.7</literal>)</entry>
</row>
@ -156,7 +159,7 @@
<row>
<entry><varname>LOCALBASE</varname></entry>
<entry>The base of the <quote>local</quote> tree (e.g.,
<entry>The base of the <quote>local</quote> tree (for example,
<literal>/usr/local</literal>)</entry>
</row>
@ -172,12 +175,12 @@
</informaltable>
<note>
<para>If you have to define the variable
<varname>MASTERDIR</varname>, do so before including
<para>When <varname>MASTERDIR</varname> is needed, always define
it before including
<filename>bsd.port.pre.mk</filename>.</para>
</note>
<para>Here are some examples of things you can write after
<para>Here are some examples of things that can be added after
<filename>bsd.port.pre.mk</filename>:</para>
<programlisting># no need to compile lang/perl5 if perl5 is already in system
@ -185,9 +188,8 @@
BROKEN= perl is in system
.endif</programlisting>
<para>You did remember to use tab instead of spaces after
<literal>BROKEN=</literal> and
<!-- smiley -->:-).</para>
<para>Always use tab instead of spaces after
<literal>BROKEN=</literal>.</para>
</sect1>
<sect1 xml:id="dads-sh-exec">
@ -213,21 +215,20 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<sect1 xml:id="dads-rational">
<title>Do Things Rationally</title>
<para>The <filename>Makefile</filename> should do things simply
and reasonably. If you can make it a couple of lines shorter or
more readable, then do so. Examples include using a make
<para>The <filename>Makefile</filename> should do things in a
simple and reasonable manner. Making it a couple of lines shorter or
more readable is always better. Examples include using a make
<literal>.if</literal> construct instead of a shell
<literal>if</literal> construct, not redefining
<buildtarget>do-extract</buildtarget> if you can redefine
<varname>EXTRACT*</varname> instead, and using
<buildtarget>do-extract</buildtarget> if redefining
<varname>EXTRACT*</varname> is enough, and using
<varname>GNU_CONFIGURE</varname> instead of
<literal>CONFIGURE_ARGS
+= --prefix=&dollar;{PREFIX}</literal>.</para>
<para>If you find yourself having to write a lot of new code to
try to do something, please go back and review
<filename>bsd.port.mk</filename> to see if it contains an
existing implementation of what you are trying to do. While
<para>If a lot of new code is needed to do something, there may
already be an implementation of it in
<filename>bsd.port.mk</filename>. While
hard to read, there are a great many seemingly-hard problems for
which <filename>bsd.port.mk</filename> already provides a
shorthand solution.</para>
@ -238,7 +239,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<varname>CXX</varname></title>
<para>The port must respect both <varname>CC</varname> and
<varname>CXX</varname> variables. What we mean by this is that
<varname>CXX</varname>. What we mean by this is that
the port must not set the values of these variables absolutely,
overriding existing values; instead, it may append whatever
values it needs to the existing values. This is so that build
@ -249,24 +250,23 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<literal>NO_PACKAGE=ignores either cc or cxx</literal> to the
<filename>Makefile</filename>.</para>
<para>An example of a <filename>Makefile</filename> respecting
both <varname>CC</varname> and <varname>CXX</varname>
variables follows. Note the <varname>?=</varname>:</para>
<para>Here is an example of a <filename>Makefile</filename> respecting
both <varname>CC</varname> and <varname>CXX</varname>.
Note the <literal>?=</literal>:</para>
<programlisting>CC?= gcc</programlisting>
<programlisting>CXX?= g++</programlisting>
<para>Here is an example which respects neither
<varname>CC</varname> nor <varname>CXX</varname>
variables:</para>
<varname>CC</varname> nor <varname>CXX</varname>:</para>
<programlisting>CC= gcc</programlisting>
<programlisting>CXX= g++</programlisting>
<para>Both <varname>CC</varname> and <varname>CXX</varname>
variables can be defined on &os; systems in
can be defined on &os; systems in
<filename>/etc/make.conf</filename>. The first example defines
a value if it was not previously set in
<filename>/etc/make.conf</filename>, preserving any system-wide
@ -277,10 +277,10 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<sect1 xml:id="dads-cflags">
<title>Respect <varname>CFLAGS</varname></title>
<para>The port must respect the <varname>CFLAGS</varname>
variable. What we mean by this is that the port must not set
<para>The port must respect <varname>CFLAGS</varname>.
What we mean by this is that the port must not set
the value of this variable absolutely, overriding the existing
value; instead, it may append whatever values it needs to the
value. Instead, it may append whatever values it needs to the
existing value. This is so that build options that affect all
ports can be set globally.</para>
@ -288,26 +288,26 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<literal>NO_PACKAGE=ignores cflags</literal> to the
<filename>Makefile</filename>.</para>
<para>An example of a <filename>Makefile</filename> respecting
the <varname>CFLAGS</varname> variable follows. Note the
<varname>+=</varname>:</para>
<para>Here is an example of a <filename>Makefile</filename> respecting
<varname>CFLAGS</varname>. Note the
<literal>+=</literal>:</para>
<programlisting>CFLAGS+= -Wall -Werror</programlisting>
<para>Here is an example which does not respect the
<varname>CFLAGS</varname> variable:</para>
<para>Here is an example which does not respect
<varname>CFLAGS</varname>:</para>
<programlisting>CFLAGS= -Wall -Werror</programlisting>
<para>The <varname>CFLAGS</varname> variable is defined on
<para><varname>CFLAGS</varname> is defined on
&os; systems in <filename>/etc/make.conf</filename>. The first
example appends additional flags to the
<varname>CFLAGS</varname> variable, preserving any system-wide
example appends additional flags to
<varname>CFLAGS</varname>, preserving any system-wide
definitions. The second example clobbers anything previously
defined.</para>
<para>You should remove optimization flags from the third party
<filename>Makefile</filename>s. System
<para>Remove optimization flags from the third party
<filename>Makefile</filename>s. The system
<varname>CFLAGS</varname> contains system-wide optimization
flags. An example from an unmodified
<filename>Makefile</filename>:</para>
@ -315,8 +315,8 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting>
<para>Using system optimization flags, the
<filename>Makefile</filename> would look similar to the
following example:</para>
<filename>Makefile</filename> would look similar to this
example:</para>
<programlisting>CFLAGS+= -DHAVE_SOUND</programlisting>
</sect1>
@ -343,10 +343,9 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<sect1 xml:id="dads-feedback">
<title>Feedback</title>
<para>Do send applicable changes/patches to the original
author/maintainer for inclusion in next release of the code.
This will only make your job that much easier for the next
release.</para>
<para>Do send applicable changes and patches to the upstream
maintainer for inclusion in the next release of the code.
This makes updating to the next release that much easier.</para>
</sect1>
<sect1 xml:id="dads-readme">
@ -376,16 +375,16 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or
<varname>IGNORE</varname></title>
<para>In certain cases users should be prevented from installing
a port. To tell a user that a port should not be installed,
there are several <command>make</command> variables that can be
used in a port's <filename>Makefile</filename>. The value of
the following <command>make</command> variables will be the
reason that is given back to users for why the port refuses to
install itself. Please use the correct <command>make</command>
variable as each make variable conveys radically different
meanings to both users, and to automated systems that depend on
the <filename>Makefile</filename>s, such as
<para>In certain cases, users must be prevented from installing
a port. There are several variables that can be used in a
port's <filename>Makefile</filename> to tell the user that the
port cannot be installed. The value of
these make variables will be the
reason that is shown to users for why the port refuses to
install itself. Please use the correct make
variable. Each variable conveys radically different
meanings, both to users and to automated systems that depend on
<filename>Makefile</filename>s, such as
<link linkend="build-cluster">the ports build cluster</link>,
<link linkend="freshports">FreshPorts</link>, and
<link linkend="portsmon">portsmon</link>.</para>
@ -397,7 +396,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<listitem>
<para><varname>BROKEN</varname> is reserved for ports that
currently do not compile, install, deinstall, or run
correctly. It should be used for ports where the problem
correctly. Use it for ports where the problem
is believed to be temporary.</para>
<para>If instructed, the build cluster will still attempt
@ -441,11 +440,11 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<para><varname>FORBIDDEN</varname> is used for ports that
contain a security vulnerability or induce grave concern
regarding the security of a &os; system with a given port
installed (e.g., a reputably insecure program or a program
that provides easily exploitable services). Ports should
be marked as <varname>FORBIDDEN</varname> as soon as a
installed (for example, a reputably insecure program or a program
that provides easily exploitable services). Mark ports
as <varname>FORBIDDEN</varname> as soon as a
particular piece of software has a vulnerability and there
is no released upgrade. Ideally ports should be upgraded
is no released upgrade. Ideally upgrade ports
as soon as possible when a security vulnerability is
discovered so as to reduce the number of vulnerable &os;
hosts (we like being known for being secure), however
@ -458,8 +457,8 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<listitem>
<para><varname>IGNORE</varname> is reserved for ports that
should not be built for some other reason. It should be
used for ports where the problem is believed to be
must not be built for some other reason. Use it
for ports where the problem is believed to be
structural. The build cluster will not, under any
circumstances, build ports marked as
<varname>IGNORE</varname>. For instance, use
@ -497,10 +496,10 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
</listitem>
<listitem>
<para>If a port should be marked <varname>IGNORE</varname>
<para>To mark a port as <varname>IGNORE</varname>d
only on certain architectures, there are two other
convenience variables that will automatically set
<varname>IGNORE</varname> for you:
<varname>IGNORE</varname>:
<varname>ONLY_FOR_ARCHS</varname> and
<varname>NOT_FOR_ARCHS</varname>. Examples:</para>
@ -519,11 +518,10 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<listitem>
<para>If a port fetches i386 binaries and installs them,
<varname>IA32_BINARY_PORT</varname> should be set. If
this variable is set, it will be checked whether the
<filename>/usr/lib32</filename> directory is available for
IA32 versions of libraries and whether the kernel has IA32
compatibility compiled in. If one of these two
set <varname>IA32_BINARY_PORT</varname>. If this variable
is set, <filename>/usr/lib32</filename> must be present
for IA32 versions of libraries and the kernel must support
IA32 compatibility. If one of these two
dependencies is not satisfied, <varname>IGNORE</varname>
will be set automatically.</para>
</listitem>
@ -533,15 +531,16 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<sect2 xml:id="dads-noinstall-notes">
<title>Implementation Notes</title>
<para>The strings should not be quoted. Also, the wording of
the string should be somewhat different due to the way the
information is shown to the user. Examples:</para>
<para>Do not quote the values of <varname>BROKEN</varname>,
<varname>IGNORE</varname>, and related variables. Due to the
way the information is shown to the user, the wording of
messages for each variable differ:</para>
<programlisting>BROKEN= fails to link with base -lcrypto</programlisting>
<programlisting>IGNORE= unsupported on recent versions</programlisting>
<para>resulting in the following output from
<para>resulting in this output from
<command>make describe</command>:</para>
<programlisting>===&gt; foobar-0.1 is marked as broken: fails to link with base -lcrypto.</programlisting>
@ -558,11 +557,11 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<para>Do remember that <varname>BROKEN</varname> and
<varname>FORBIDDEN</varname> are to be used as a temporary
resort if a port is not working. Permanently broken ports
should be removed from the tree entirely.</para>
will be removed from the tree entirely.</para>
<para>When it makes sense to do so, users can be warned about
a pending port removal with <varname>DEPRECATED</varname> and
<varname>EXPIRATION_DATE</varname>. The former is simply a
<varname>EXPIRATION_DATE</varname>. The former is a
string stating why the port is scheduled for removal; the latter
is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown
to the user.</para>
@ -621,8 +620,8 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<command>make index</command>, then has to run the command,
further slowing down that process.</para>
<para>Usage of &man.sysctl.8; should always be done with the
<varname>SYSCTL</varname> variable, as it contains the fully
<para>Only use &man.sysctl.8; through
<varname>SYSCTL</varname>, as it contains the fully
qualified path and can be overridden, if one has such a
special need.</para>
</sect1>
@ -631,21 +630,21 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<title>Rerolling Distfiles</title>
<para>Sometimes the authors of software change the content of
released distfiles without changing the file's name. You have
to verify that the changes are official and have been performed
released distfiles without changing the file's name.
Verify that the changes are official and have been performed
by the author. It has happened in the past that the distfile
was silently altered on the download servers with the intent to
cause harm or compromise end user security.</para>
<para>Put the old distfile aside, download the new one, unpack
them and compare the content with &man.diff.1;. If you see
nothing suspicious, you can update
them and compare the content with &man.diff.1;. If there is
nothing suspicious, update
<filename>distinfo</filename>. Be sure to summarize the
differences in your PR or commit log, so that other people know
that you have taken care to ensure that nothing bad has
differences in the PR or commit log, so that other people know
that nothing bad has
happened.</para>
<para>You might also want to contact the authors of the software
<para>Contact the authors of the software
and confirm the changes with them.</para>
</sect1>
@ -653,12 +652,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<title>Avoiding Linuxisms</title>
<para>Do not use <filename>/proc</filename> if there are any
other ways of getting the information, e.g.,
other ways of getting the information. For example,
<function>setprogname(argv[0])</function> in
<function>main()</function> and then &man.getprogname.3; if
you want to <quote>know your name</quote>.</para>
<function>main()</function> and then &man.getprogname.3;
to know the executable name>.</para>
<para>Do not rely on behaviour that is undocumented by
<para>Do not rely on behavior that is undocumented by
<acronym>POSIX</acronym>.</para>
<para>Do not record timestamps in the critical path of the
@ -704,7 +703,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para>
<para>Check that headers are included in the
<acronym>POSIX</acronym> or man page recommended way, e.g.,
<acronym>POSIX</acronym> or man page recommended way. For example,
<filename>sys/types.h</filename> is often forgotten, which is
not as much of a problem for &linux; as it is for &os;.</para>
@ -716,9 +715,9 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
<sect1 xml:id="dads-misc">
<title>Miscellanea</title>
<para>The files <filename>pkg-descr</filename> and
<filename>pkg-plist</filename> should each be double-checked.
If you are reviewing a port and feel they can be worded better,
<para>Always double-check <filename>pkg-descr</filename> and
<filename>pkg-plist</filename>.
If reviewing a port and a better wording can be achieved,
do so.</para>
<para>Do not copy more copies of the GNU General Public License