Index: en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
@@ -17,9 +17,9 @@
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 PR
+ xlink:href="http://bugs.FreeBSD.org/search/">PR
database that others have submitted. Submit any
- comments on ports you check as described in Bug
Reports and General Commentary. Checking ports in the
PR database will both make it faster for us to commit them, and
@@ -35,18 +35,18 @@
build (see
installing ports from a CDROM for an example of
- building ports from a read-only tree). If you need to modify
- one of the pkg-*
- files, do so by redefining a
+ building ports from a read-only tree). To modify
+ one of pkg-*,
+ do so by redefining a
variable, not by writing over it.WRKDIRPREFIX
- Make sure your port honors WRKDIRPREFIX.
- Most ports do not have to worry about this. In particular, if
- you are referring to a WRKDIR of another
+ Make sure the port honors WRKDIRPREFIX.
+ Most ports do not have to worry about this. In particular, when
+ referring to a WRKDIR of another
port, note that the correct location is
WRKDIRPREFIXPORTSDIR/subdir/name/work
not
@@ -55,8 +55,8 @@
.CURDIR/../../subdir/name/work
or some such.
- Also, if you are defining WRKDIR
- yourself, make sure you prepend
+ Also, if defining WRKDIR,
+ make sure to prepend
${WRKDIRPREFIX}${.CURDIR} in
the front.
@@ -64,7 +64,7 @@
Differentiating Operating Systems and OS Versions
- You may come across code that needs modifications or
+ When 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 __FreeBSD_version and
@@ -97,15 +97,15 @@
.include <bsd.port.mk> line. It
usually can be avoided by including
bsd.port.pre.mk somewhere in the middle of
- your Makefile and
+ the Makefile and
bsd.port.post.mk at the end.
-
- Include either the
+
+ Include either
bsd.port.pre.mk/bsd.port.post.mk
pair or bsd.port.mk only; do not mix
these two usages.
-
+
bsd.port.pre.mk only defines a few
variables, which can be used in tests in the
@@ -130,20 +130,20 @@
ARCHThe architecture as returned by uname
- -m (e.g., i386)
+ -m (for example, i386)
OPSYSThe operating system type, as returned by
- uname -s (e.g.,
+ uname -s (for example,
FreeBSD)OSRELThe release version of the operating system
- (e.g., 2.1.5 or
+ (for example, 2.1.5 or
2.2.7)
@@ -156,7 +156,7 @@
LOCALBASE
- The base of the local tree (e.g.,
+ The base of the local tree (for example,
/usr/local)
@@ -172,12 +172,12 @@
- If you have to define the variable
- MASTERDIR, do so before including
+ When MASTERDIR is needed, always define
+ it before including
bsd.port.pre.mk.
- Here are some examples of things you can write after
+ Here are some examples of things that can be written after
bsd.port.pre.mk:# no need to compile lang/perl5 if perl5 is already in system
@@ -185,7 +185,7 @@
BROKEN= perl is in system
.endif
- You did remember to use tab instead of spaces after
+ Always use tab instead of spaces after
BROKEN= and
:-).
@@ -213,21 +213,20 @@
Do Things Rationally
- The Makefile 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
+ The Makefile should do things in a
+ simple and resaonnable manner. Making it a couple of lines shorter or
+ more readable, is always better. Examples include using a make
.if construct instead of a shell
if construct, not redefining
- do-extract if you can redefine
- EXTRACT* instead, and using
+ do-extract if redefining
+ EXTRACT* is enough, and using
GNU_CONFIGURE instead of
CONFIGURE_ARGS
+= --prefix=${PREFIX}.
- If you find yourself having to write a lot of new code to
- try to do something, please go back and review
- bsd.port.mk to see if it contains an
- existing implementation of what you are trying to do. While
+ If a lot of new code is needed to do something, there may
+ already be an implementation of it in
+ bsd.port.mk. While
hard to read, there are a great many seemingly-hard problems for
which bsd.port.mk already provides a
shorthand solution.
@@ -238,7 +237,7 @@
CXXThe port must respect both CC and
- CXX variables. What we mean by this is that
+ CXX. 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
@@ -251,22 +250,21 @@
An example of a Makefile respecting
both CC and CXX
- variables follows. Note the ?=:
+ follows. Note the ?=:CC?= gccCXX?= g++Here is an example which respects neither
- CC nor CXX
- variables:
+ CC nor CXX:CC= gccCXX= g++Both CC and CXX
- variables can be defined on &os; systems in
+ can be defined on &os; systems in
/etc/make.conf. The first example defines
a value if it was not previously set in
/etc/make.conf, preserving any system-wide
@@ -277,8 +275,8 @@
Respect CFLAGS
- The port must respect the CFLAGS
- variable. What we mean by this is that the port must not set
+ The port must respect CFLAGS.
+ 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
existing value. This is so that build options that affect all
@@ -289,24 +287,24 @@
Makefile.An example of a Makefile respecting
- the CFLAGS variable follows. Note the
- +=:
+ CFLAGS follows. Not
+ +=:CFLAGS+= -Wall -Werror
- Here is an example which does not respect the
- CFLAGS variable:
+ Here is an example which does not respect
+ CFLAGS:CFLAGS= -Wall -Werror
- The CFLAGS variable is defined on
+ CFLAGS is defined on
&os; systems in /etc/make.conf. The first
- example appends additional flags to the
- CFLAGS variable, preserving any system-wide
+ example appends additional flags to
+ CFLAGS, preserving any system-wide
definitions. The second example clobbers anything previously
defined.
- You should remove optimization flags from the third party
+ Remove optimization flags from the third party
Makefiles. System
CFLAGS contains system-wide optimization
flags. An example from an unmodified
@@ -315,8 +313,8 @@
CFLAGS= -O3 -funroll-loops -DHAVE_SOUNDUsing system optimization flags, the
- Makefile would look similar to the
- following example:
+ Makefile would look similar to this
+ example:CFLAGS+= -DHAVE_SOUND
@@ -345,7 +343,7 @@
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
+ This will only make the job that much easier for the next
release.
@@ -376,11 +374,11 @@
BROKEN, FORBIDDEN, or
IGNORE
- In certain cases users should be prevented from installing
- a port. To tell a user that a port should not be installed,
+ In certain cases users must be prevented from installing
+ a port. To tell a user that a port must not be installed,
there are several make variables that can be
used in a port's Makefile. The value of
- the following make variables will be the
+ these make variables will be the
reason that is given back to users for why the port refuses to
install itself. Please use the correct make
variable as each make variable conveys radically different
@@ -397,7 +395,7 @@
BROKEN 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.If instructed, the build cluster will still attempt
@@ -441,11 +439,11 @@
FORBIDDEN 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 FORBIDDEN as soon as a
+ installed (for example, a reputably insecure program or a program
+ that provides easily exploitable services). Mark ports
+ as FORBIDDEN 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 +456,8 @@
IGNORE 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
IGNORE. For instance, use
@@ -497,10 +495,10 @@
- If a port should be marked IGNORE
+ To mark a port as IGNOREd
only on certain architectures, there are two other
convenience variables that will automatically set
- IGNORE for you:
+ IGNORE:
ONLY_FOR_ARCHS and
NOT_FOR_ARCHS. Examples:
@@ -519,9 +517,9 @@
If a port fetches i386 binaries and installs them,
- IA32_BINARY_PORT should be set. If
- this variable is set, it will be checked whether the
- /usr/lib32 directory is available for
+ set IA32_BINARY_PORT. If
+ this variable is set, it will be checked whether
+ /usr/lib32 is available for
IA32 versions of libraries and whether the kernel has IA32
compatibility compiled in. If one of these two
dependencies is not satisfied, IGNORE
@@ -533,15 +531,16 @@
Implementation Notes
- 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:
+ Do not quote the values of BROKEN,
+ IGNORE, and related variables. Also, due
+ to the way the information is shown to the user, their
+ wordings should be different. Examples:BROKEN= fails to link with base -lcryptoIGNORE= unsupported on recent versions
- resulting in the following output from
+ resulting in this output from
make describe:===> foobar-0.1 is marked as broken: fails to link with base -lcrypto.
@@ -558,11 +557,11 @@
Do remember that BROKEN and
FORBIDDEN are to be used as a temporary
resort if a port is not working. Permanently broken ports
- should be removed from the tree entirely.
+ will be removed from the tree entirely.When it makes sense to do so, users can be warned about
a pending port removal with DEPRECATED and
- EXPIRATION_DATE. The former is simply a
+ EXPIRATION_DATE. 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.
@@ -621,8 +620,8 @@
make index, then has to run the command,
further slowing down that process.
- Usage of &man.sysctl.8; should always be done with the
- SYSCTL variable, as it contains the fully
+ Only use &man.sysctl.8; through
+ SYSCTL, as it contains the fully
qualified path and can be overridden, if one has such a
special need.
@@ -631,21 +630,21 @@
Rerolling DistfilesSometimes 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.
+ Check 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.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
distinfo. 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.
- You might also want to contact the authors of the software
+ Maybe also contact the authors of the software
and confirm the changes with them.
@@ -653,10 +652,10 @@
Avoiding LinuxismsDo not use /proc if there are any
- other ways of getting the information, e.g.,
+ other ways of getting the information, for example,
setprogname(argv[0]) in
- main() and then &man.getprogname.3; if
- you want to know your name.
+ main() and then &man.getprogname.3;
+ to know the executable name.Do not rely on behaviour that is undocumented by
POSIX.
@@ -704,7 +703,7 @@
xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here.Check that headers are included in the
- POSIX or man page recommended way, e.g.,
+ POSIX or man page recommended way, for example,
sys/types.h is often forgotten, which is
not as much of a problem for &linux; as it is for &os;.
@@ -716,9 +715,9 @@
Miscellanea
- The files pkg-descr and
- pkg-plist should each be double-checked.
- If you are reviewing a port and feel they can be worded better,
+ Always double-check pkg-descr and
+ pkg-plist.
+ If reviewing a port and a better wording can be achieved,
do so.Do not copy more copies of the GNU General Public License