svn commit: r45616 - head/en_US.ISO8859-1/books/porters-handbook/special
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 16 12:01:30 UTC 2014
Author: mat (ports committer)
Date: Tue Sep 16 12:01:29 2014
New Revision: 45616
URL: http://svnweb.freebsd.org/changeset/doc/45616
Log:
igor -Ry and some other rewording and fixes.
Differential Revision: https://reviews.freebsd.org/D653
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Sep 16 11:58:50 2014 (r45615)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Sep 16 12:01:29 2014 (r45616)
@@ -10,16 +10,15 @@
<title>Special Considerations</title>
- <para>There are some more things you have to take into account
- when you create a port. This section explains the most common
- of those.</para>
+ <para>This section explains the most common things to consider when
+ creating a port.</para>
<sect1 xml:id="staging">
<title>Staging</title>
<para><filename>bsd.port.mk</filename> expects ports to work
with a <quote>stage directory</quote>. This means that a port
- should not install files directly to the regular destination
+ must not install files directly to the regular destination
directories (that is, under <varname>PREFIX</varname>, for
example) but instead into a separate directory from which the
package is then built. In many cases, this does not require
@@ -42,7 +41,7 @@
<note>
<para>The vast majority of ports do not <emphasis>really
- need</emphasis> to be root. You can mostly avoid it by
+ need</emphasis> to be root. It can mostly be avoided by
using <link
linkend="uses-uidfix"><literal>USES=uidfix</literal></link>,
and from time to time by slightly patching the port's
@@ -50,7 +49,7 @@
</note>
<para>Meta ports, or ports that do not install files themselves
- but only depend on other ports, should avoid needlessly
+ but only depend on other ports, must avoid needlessly
extracting the &man.mtree.8; to the stage directory. This is
the basic directory layout of the package, and these empty
directories will be seen as orphans. To prevent
@@ -58,8 +57,8 @@
<programlisting>NO_MTREE= yes</programlisting>
- <para>Staging is enabled by prepending the
- <varname>STAGEDIR</varname> variable to paths used in the
+ <para>Staging is enabled by prepending
+ <varname>STAGEDIR</varname> to paths used in the
<buildtarget>pre-install</buildtarget>,
<buildtarget>do-install</buildtarget>, and
<buildtarget>post-install</buildtarget> targets (see the
@@ -72,21 +71,21 @@
absolute paths whenever possible.</para>
<para>When creating a symlink, <varname>STAGEDIR</varname>
- should be prepended to the target path only. For
+ is prepended to the target path only. For
example:</para>
- <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting>
+ <programlisting>${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
<para>The source path
- <filename>${PREFIX}/lib/libfoo.so.42</filename> looks fine but
+ <filename>${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable></filename> looks fine but
could, in fact, be incorrect. Absolute paths can point to a
wrong location, like when a remote file system has been
mounted with <acronym>NFS</acronym> under a non-root mount
point. Relative paths are less fragile, and often much
shorter.</para>
- <para>Ports that install kernel modules must prepend the
- <varname>STAGEDIR</varname> variable to
+ <para>Ports that install kernel modules must prepend
+ <varname>STAGEDIR</varname> to
their destination, by default
<filename>/boot/modules</filename>.</para>
</sect1>
@@ -106,7 +105,7 @@
distribution file. The second approach seems easier at
first, but there are some serious drawbacks:</para>
- <para>The following list is loosely based on the <link
+ <para>This list is loosely based on the <link
xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link>
and <link
xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>
@@ -220,7 +219,7 @@
port. If such a port does not exist yet, consider creating
it.</para>
- <para>Bundled libraries should only be used if upstream has a
+ <para>Only use bundled libraries if the upstream has a
good track record on security and using unbundled versions
leads to overly complex patches.</para>
</sect2>
@@ -229,7 +228,7 @@
<sect1 xml:id="porting-shlibs">
<title>Shared Libraries</title>
- <para>If your port installs one or more shared libraries, define
+ <para>If the port installs one or more shared libraries, define
a <varname>USE_LDCONFIG</varname> make variable, which will
instruct a <filename>bsd.port.mk</filename> to run
<literal>${LDCONFIG} -m</literal> on the directory
@@ -239,21 +238,21 @@
into the shared library cache. This variable, when defined,
will also facilitate addition of an appropriate
<literal>@exec /sbin/ldconfig -m</literal> and
- <literal>@unexec /sbin/ldconfig -R</literal> pair into your
- <filename>pkg-plist</filename> file, so that a user who
+ <literal>@unexec /sbin/ldconfig -R</literal> pair into
+ <filename>pkg-plist</filename>, so that a user who
installed the package can start using the shared library
immediately and de-installation will not cause the system to
still believe the library is there.</para>
<programlisting>USE_LDCONFIG= yes</programlisting>
- <para>If you need, you can override the default directory by
- setting the <varname>USE_LDCONFIG</varname> value to a list of
+ <para>The default directory can be overridden by
+ setting <varname>USE_LDCONFIG</varname> to a list of
directories into which shared libraries are to be installed.
- For example if your port installs shared libraries into
+ For example, if the port installs shared libraries into
<filename>PREFIX/lib/foo</filename> and
<filename>PREFIX/lib/bar</filename>
- directories you could use the following in your
+ use this in
<filename>Makefile</filename>:</para>
<programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
@@ -270,14 +269,14 @@
<para>When installing 32-bit libraries on 64-bit system, use
<varname>USE_LDCONFIG32</varname> instead.</para>
- <para>If the software you are porting uses <link
+ <para>If the software uses <link
linkend="using-autotools">autotools</link>, and specifically
- <command>libtool</command>, you should add <link
+ <command>libtool</command>, add <link
linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para>
<para>When the major library version number increments in the
update to the new port version, all other ports that link to
- the affected library should have their
+ the affected library must have their
<varname>PORTREVISION</varname> incremented, to force
recompilation with the new library version.</para>
</sect1>
@@ -291,7 +290,7 @@
profit, and so on.</para>
<important>
- <para>It is your responsibility as a porter to read the
+ <para>It is the responsibility of a porter to read the
licensing terms of the software and make sure that the
&os; project will not be held accountable for violating
them by redistributing the source or compiled binaries
@@ -300,7 +299,7 @@
</important>
<para>In situations like this, the variables described in the
- following sections can be set.</para>
+ next sections can be set.</para>
<sect2 xml:id="porting-restrictions-no_package">
<title><varname>NO_PACKAGE</varname></title>
@@ -316,15 +315,16 @@
on a CD-ROM (or similar media) unless
<varname>NO_CDROM</varname> is set as well.</para>
- <para><varname>NO_PACKAGE</varname> should also be used if the
+ <para>If the
binary package is not generally useful, and the application
- should always be compiled from the source code. For
+ must always be compiled from the source code, use
+ <varname>NO_PACKAGE</varname>. For
example, if the application has configuration information
- that is site specific hard coded in to it at compile time,
+ that is site specific hard coded into it at compile time,
set <varname>NO_PACKAGE</varname>.</para>
- <para><varname>NO_PACKAGE</varname> should be set to a string
- describing the reason why the package should not be
+ <para>Set <varname>NO_PACKAGE</varname> to a string
+ describing the reason why the package cannot be
generated.</para>
</sect2>
@@ -343,9 +343,9 @@
<varname>DISTFILES</varname> will be available, and only via
FTP/HTTP.</para>
- <para><varname>NO_CDROM</varname> should be set to a string
+ <para>Set <varname>NO_CDROM</varname> to a string
describing the reason why the port cannot be redistributed
- on CD-ROM. For instance, this should be used if the port's
+ on CD-ROM. For instance, use this if the port's
license is for <quote>non-commercial</quote> use
only.</para>
</sect2>
@@ -353,13 +353,13 @@
<sect2 xml:id="porting-restrictions-nofetchfiles">
<title><varname>NOFETCHFILES</varname></title>
- <para>Files defined in the <varname>NOFETCHFILES</varname>
- variable are not fetchable from any of the
+ <para>Files defined in <varname>NOFETCHFILES</varname>
+ are not fetchable from any of
<varname>MASTER_SITES</varname>. An example of such a file
is when the file is supplied on CD-ROM by the vendor.</para>
<para>Tools which check for the availability of these files
- on the <varname>MASTER_SITES</varname> should ignore these
+ on <varname>MASTER_SITES</varname> have to ignore these
files and not report about them.</para>
</sect2>
@@ -371,12 +371,12 @@
<varname>DISTFILES</varname> nor distributing the binary
package in any way.</para>
- <para><varname>NO_CDROM</varname> or
- <varname>NO_PACKAGE</varname> should not be set along with
- <varname>RESTRICTED</varname> since the latter variable
+ <para>Do not set <varname>NO_CDROM</varname> or
+ <varname>NO_PACKAGE</varname> along with
+ <varname>RESTRICTED</varname>, since the latter variable
implies the former ones.</para>
- <para><varname>RESTRICTED</varname> should be set to a string
+ <para>Set <varname>RESTRICTED</varname> to a string
describing the reason why the port cannot be redistributed.
Typically, this indicates that the port contains proprietary
software and that the user will need to manually download
@@ -400,10 +400,10 @@
<title><varname>LEGAL_TEXT</varname></title>
<para>If the port has legal concerns not addressed by the
- above variables, the variable <varname>LEGAL_TEXT</varname>
- should be set to a string explaining the concern. For
+ above variables, set <varname>LEGAL_TEXT</varname>
+ to a string explaining the concern. For
example, if special permission was obtained for &os; to
- redistribute the binary, this variable should indicate
+ redistribute the binary, this variable must indicate
so.</para>
</sect2>
@@ -482,8 +482,8 @@ IGNORE= may not be redistributed because
implementation is listed in <literal>USES</literal>, the
variables <varname>GMAKE</varname> (for the
<acronym>GNU</acronym> version) or <varname>FMAKE</varname>
- (for the legacy &os; version) are available. Most ports
- should only use <varname>MAKE_CMD</varname> within the
+ (for the legacy &os; version) are available.
+ Only use <varname>MAKE_CMD</varname> within the
application <filename>Makefile</filename>s in
<varname>WRKSRC</varname> to call the
<command>make</command> implementation expected by the
@@ -497,10 +497,10 @@ IGNORE= may not be redistributed because
linkend="uses-imake"><literal>USES=imake</literal></link>
section of <xref linkend="uses"/> for more details.</para>
- <para>If your port's source <filename>Makefile</filename> has
- something else than <buildtarget>all</buildtarget> as the
+ <para>If the port's source <filename>Makefile</filename> has
+ something other than <buildtarget>all</buildtarget> as the
main build target, set <varname>ALL_TARGET</varname>
- accordingly. Same goes for
+ accordingly. The same goes for
<buildtarget>install</buildtarget> and
<varname>INSTALL_TARGET</varname>.</para>
</sect2>
@@ -508,10 +508,10 @@ IGNORE= may not be redistributed because
<sect2 xml:id="using-configure">
<title><command>configure</command> Script</title>
- <para>If your port uses the <command>configure</command>
- script to generate <filename>Makefile</filename> files from
- <filename>Makefile.in</filename> files, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
+ <para>If the port uses the <command>configure</command>
+ script to generate <filename>Makefile</filename> from
+ <filename>Makefile.in</filename>, set
+ <literal>GNU_CONFIGURE=yes</literal>. To give
extra arguments to the <command>configure</command> script
(the default argument is <literal>--prefix=${PREFIX}
--infodir=${PREFIX}/${INFO_PATH}
@@ -519,7 +519,7 @@ IGNORE= may not be redistributed because
--build=${CONFIGURE_TARGET}</literal>), set those
extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
environment variables can be passed using
- <varname>CONFIGURE_ENV</varname> variable.</para>
+ <varname>CONFIGURE_ENV</varname>.</para>
<table frame="none" xml:id="using-configure-variables">
<title>Variables for Ports That Use
@@ -624,8 +624,8 @@ IGNORE= may not be redistributed because
</table>
<table frame="none" xml:id="using-cmake-user-variables">
- <title>Variables the Users can define for
- <command>cmake</command> builds</title>
+ <title>Variables the Users Can Define for
+ <command>cmake</command> Builds</title>
<tgroup cols="2">
<thead>
@@ -653,7 +653,7 @@ IGNORE= may not be redistributed because
</tgroup>
</table>
- <para><application>CMake</application> supports the following
+ <para><application>CMake</application> supports these
build profiles: <literal>Debug</literal>,
<literal>Release</literal>,
<literal>RelWithDebInfo</literal> and
@@ -664,14 +664,14 @@ IGNORE= may not be redistributed because
<varname>CFLAGS</varname> to <literal>-O2 -g</literal> and
<literal>-Os -DNDEBUG</literal> correspondingly. The
lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is
- exported to the <varname>PLIST_SUB</varname> and should be
- used if port installs <literal>*.cmake</literal> files
+ exported to <varname>PLIST_SUB</varname> and must be
+ used if the port installs <filename><replaceable>*</replaceable>.cmake</filename>
depending on the build type (see
<package role="port">deskutils/strigi</package> for an
example). Please note that some projects may define their
own build profiles and/or force particular build type by
setting <literal>CMAKE_BUILD_TYPE</literal> in
- <filename>CMakeLists.txt </filename> files. In order to
+ <filename>CMakeLists.txt</filename>. To
make a port for such a project respect
<varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>,
the <literal>CMAKE_BUILD_TYPE</literal> definitions must be
@@ -692,7 +692,7 @@ IGNORE= may not be redistributed because
<example xml:id="using-cmake-example">
<title><literal>USES= cmake</literal> Example</title>
- <para>The following snippet demonstrates the use of
+ <para>This snippet demonstrates the use of
<application>CMake</application> for a port.
<varname>CMAKE_SOURCE_PATH</varname> is not usually
required, but can be set when the sources are not located
@@ -707,7 +707,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
<sect2 xml:id="using-scons">
<title>Using <command>scons</command></title>
- <para>If your port uses <application>SCons</application>,
+ <para>If the port uses <application>SCons</application>,
define <literal>USE_SCONS=yes</literal>.</para>
<table frame="none" xml:id="using-scons-variables">
@@ -753,7 +753,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
<para>To make third party <filename>SConstruct</filename>
respect everything that is passed to SCons in
<varname>SCONS_ENV</varname> (that is, most importantly,
- <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the
+ <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch
<filename>SConstruct</filename> so build
<literal>Environment</literal> is constructed like
this:</para>
@@ -842,9 +842,9 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
<command>autoheader</command></title>
<para>Some ports do not contain a configure script, but do
- contain an autoconf template in the
- <filename>configure.ac</filename> file. You can use the
- following assignments to let <command>autoconf</command>
+ contain an autoconf template in
+ <filename>configure.ac</filename>. Use these
+ assignments to let <command>autoconf</command>
create the configure script, and also have
<command>autoheader</command> create template headers for
use by the configure script.</para>
@@ -872,14 +872,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
<command>aclocal</command></title>
<para>Some packages only contain
- <filename>Makefile.am</filename> files. These have to be
- converted into <filename>Makefile.in</filename> files using
+ <filename>Makefile.am</filename>. These have to be
+ converted into <filename>Makefile.in</filename> using
<command>automake</command>, and the further processed by
<command>configure</command> to generate an actual
<filename>Makefile</filename>.</para>
<para>Similarly, packages occasionally do not ship with
- included <filename>aclocal.m4</filename> files, again
+ an included <filename>aclocal.m4</filename>, again
required to build the software. This can be achieved with
<command>aclocal</command>, which scans
<filename>configure.ac</filename> or
@@ -914,8 +914,8 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
<sect2 xml:id="using-gettext-basic">
<title>Basic Usage</title>
- <para>If your port requires <literal>gettext</literal>, set
- <literal>USES= gettext</literal>, and your port will inherit
+ <para>If the port requires <literal>gettext</literal>, set
+ <literal>USES= gettext</literal>, and the port will inherit
a dependency on <filename>libintl.so</filename> from
<package role="port">devel/gettext</package>. Other
values for <literal>gettext</literal> usage are listed in
@@ -945,13 +945,13 @@ GNU_CONFIGURE= yes</programlisting>
<sect2 xml:id="using-gettext-optional">
<title>Optional Usage</title>
- <para>Some software products allow for disabling NLS, e.g.,
+ <para>Some software products allow for disabling <acronym>NLS</acronym>. For example,
through passing <option>--disable-nls</option> to
- <command>configure</command>. In that case, your port
- should use <literal>gettext</literal> conditionally,
- depending on the status of the <varname>NLS</varname>
- option. For ports of low to medium complexity, you can rely
- on the following idiom:</para>
+ <command>configure</command>. In that case, the port
+ must use <literal>gettext</literal> conditionally,
+ depending on the status of the <literal>NLS</literal>
+ option. For ports of low to medium complexity, use
+ this idiom:</para>
<programlisting>GNU_CONFIGURE= yes
@@ -981,7 +981,7 @@ PLIST_SUB+= NLS="@comment "
.include <bsd.port.mk></programlisting>
- <para>The next item on your to-do list is to arrange so that
+ <para>The next item on the to-do list is to arrange so that
the message catalog files are included in the packing list
conditionally. The <filename>Makefile</filename> part of
this task is already provided by the idiom. It is explained
@@ -994,7 +994,7 @@ PLIST_SUB+= NLS="@comment "
Consequently, the lines prefixed by
<literal>%%NLS%%</literal> will become mere comments in the
final packing list if NLS is off; otherwise the prefix will
- be just left out. All you need to do now is insert
+ be just left out. Then insert
<literal>%%NLS%%</literal> before each path to a message
catalog file in <filename>pkg-plist</filename>. For
example:</para>
@@ -1002,8 +1002,8 @@ PLIST_SUB+= NLS="@comment "
<programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>
- <para>In high complexity cases, you may need to use more
- advanced techniques than the recipe given here, such as
+ <para>In high complexity cases, more advanced techniques
+ may be needed, such as
<link linkend="plist-dynamic">dynamic packing list
generation</link>.</para>
</sect2>
@@ -1015,7 +1015,7 @@ PLIST_SUB+= NLS="@comment "
catalog files. The target directories for them, which
reside under
<filename>LOCALBASE/share/locale</filename>,
- should rarely be created and removed by a port. The most
+ must not be created and removed by a port. The most
popular languages have their respective directories listed
in
<filename>PORTSDIR/Templates/BSD.local.dist</filename>.
@@ -1031,7 +1031,7 @@ PLIST_SUB+= NLS="@comment "
<title>Using <application>Perl</application></title>
<para>If <varname>MASTER_SITES</varname> is set to
- <literal>CPAN</literal>, the correct subdirectory should be
+ <literal>CPAN</literal>, the correct subdirectory is usually
selected automatically. If the default subdirectory is wrong,
<literal>CPAN/Module</literal> can be used to change it.
<varname>MASTER_SITES</varname> can also be set to the old
@@ -1050,13 +1050,13 @@ PLIST_SUB+= NLS="@comment "
directory. In such case, using author's id as
<varname>MASTER_SITE_SUBDIR</varname> is allowed.
The <literal>CPAN:AUTHOR</literal> macro can be used, which will
- be translated to the hashed author directory. (e.g.,
+ be translated to the hashed author directory. For example,
<literal>CPAN:AUTHOR</literal> will be converted to
- <literal>authors/id/A/AU/AUTHOR</literal>.)</para>
+ <literal>authors/id/A/AU/AUTHOR</literal>.</para>
<para>When a port needs <application>Perl</application> support,
- it should use <literal>USES=perl5</literal> with the optional
- <varname>USE_PERL5</varname> like described in <link
+ it must set <literal>USES=perl5</literal> with the optional
+ <varname>USE_PERL5</varname> described in <link
linkend="uses-perl5">the perl5 USES description</link>.</para>
<table frame="none" xml:id="using-perl-variables">
@@ -1076,22 +1076,25 @@ PLIST_SUB+= NLS="@comment "
<entry><varname>PERL</varname></entry>
<entry>The full path of the Perl 5 interpreter,
either in the system or installed from a port, but
- without the version number. Use this if you need to
- replace <quote><literal>#!</literal></quote>lines in
- scripts.</entry>
+ without the version number. Use this when the software
+ needs the path to the <application>Perl</application>
+ interpreter. To replace
+ <quote><literal>#!</literal></quote>lines in scripts,
+ use <link
+ linkend="uses-shebangfix">USES=shebangfix</link>.</entry>
</row>
<row>
<entry><varname>PERL_VERSION</varname></entry>
<entry>The full version of Perl
- installed (e.g., <literal>5.8.9</literal>).</entry>
+ installed (for example, <literal>5.8.9</literal>).</entry>
</row>
<row>
<entry><varname>PERL_LEVEL</varname></entry>
<entry>The installed Perl version as
an integer of the form <literal>MNNNPP</literal>
- (e.g., <literal>500809</literal>).</entry>
+ (for example, <literal>500809</literal>).</entry>
</row>
<row>
@@ -1104,7 +1107,7 @@ PLIST_SUB+= NLS="@comment "
<row>
<entry><varname>PERL_PORT</varname></entry>
<entry>Name of the Perl port that is
- installed (e.g., <literal>perl5</literal>).</entry>
+ installed (for example, <literal>perl5</literal>).</entry>
</row>
<row>
@@ -1119,7 +1122,7 @@ PLIST_SUB+= NLS="@comment "
<note>
<para>Ports of Perl modules which do not have an official
- website should link to <systemitem>cpan.org</systemitem> in
+ website must link to <systemitem>cpan.org</systemitem> in
the WWW line of <filename>pkg-descr</filename>. The
preferred URL form is
<literal>http://search.cpan.org/dist/Module-Name/</literal>
@@ -1168,7 +1171,7 @@ PLIST_SUB+= NLS="@comment "
<title>X.Org Components</title>
<para>The X11 implementation available in The Ports Collection
- is X.Org. If your application depends on X components, set
+ is X.Org. If the application depends on X components, set
<varname>USE_XORG</varname> to the list of required
components. Available components, at the time of writing,
are:</para>
@@ -1192,9 +1195,9 @@ PLIST_SUB+= NLS="@comment "
<filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>
<para>The Mesa Project is an effort to provide free OpenGL
- implementation. You can specify a dependency on various
- components of this project with <varname>USE_GL</varname>
- variable. Valid options are:
+ implementation. To specify a dependency on various
+ components of this project, use <varname>USE_GL</varname>.
+ Valid options are:
<literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and
<literal>linux</literal>. For backwards compatibility, the
value of <literal>yes</literal> maps to
@@ -1238,7 +1241,7 @@ USE_XORG= x11 xpm</programlisting>
<sect2 xml:id="x11-motif">
<title>Ports That Require Motif</title>
- <para>If your port requires a Motif library, define
+ <para>If the port requires a Motif library, define
<varname>USES= motif</varname> in the
<filename>Makefile</filename>. Default Motif implementation
is
@@ -1246,11 +1249,11 @@ USE_XORG= x11 xpm</programlisting>
Users can choose
<package role="port">x11-toolkits/lesstif</package>
instead by setting <varname>WANT_LESSTIF</varname>
- variable in their <filename>make.conf</filename>.</para>
+ in their <filename>make.conf</filename>.</para>
- <para>The <varname>MOTIFLIB</varname> variable will be set by
+ <para><varname>MOTIFLIB</varname> will be set by
<filename>motif.mk</filename> to reference the
- appropriate Motif library. Please patch the source of your
+ appropriate Motif library. Please patch the source of the
port to use <literal>${MOTIFLIB}</literal> wherever
the Motif library is referenced in the original
<filename>Makefile</filename> or
@@ -1263,7 +1266,7 @@ USE_XORG= x11 xpm</programlisting>
<para>If the port refers to the Motif library as
<literal>-lXm</literal> in its
<filename>Makefile</filename> or
- <filename>Imakefile</filename>, simply substitute
+ <filename>Imakefile</filename>, substitute
<literal>${MOTIFLIB}</literal> for it.</para>
</listitem>
@@ -1285,7 +1288,7 @@ USE_XORG= x11 xpm</programlisting>
<sect2 xml:id="x11-fonts">
<title>X11 Fonts</title>
- <para>If your port installs fonts for the X Window System, put
+ <para>If the port installs fonts for the X Window System, put
them in
<filename>LOCALBASE/lib/X11/fonts/local</filename>.</para>
</sect2>
@@ -1295,7 +1298,7 @@ USE_XORG= x11 xpm</programlisting>
<para>Some applications require a working X11 display for
compilation to succeed. This pose a problem for machines
- that operate headless. When the following variable is used,
+ that operate headless. When this variable is used,
the build infrastructure will start the virtual framebuffer
X server. The working <envar>DISPLAY</envar> is then passed
to the build. See <link
@@ -1329,7 +1332,7 @@ USE_XORG= x11 xpm</programlisting>
Files</title>
<para>Ports that include predefined
- <filename>*.desktop</filename> files should
+ <filename><replaceable>*</replaceable>.desktop</filename> must
include those files in <filename>pkg-plist</filename>
and install them in the
<filename>$LOCALBASE/share/applications</filename>
@@ -1350,14 +1353,14 @@ USE_XORG= x11 xpm</programlisting>
</sect3>
<sect3 xml:id="desktop-entries-macro">
- <title>Creating Desktop Entries with the
- <varname>DESKTOP_ENTRIES</varname> Macro</title>
+ <title>Creating Desktop Entries with
+ <varname>DESKTOP_ENTRIES</varname></title>
<para>Desktop entries can be easily created for applications
- by using the <varname>DESKTOP_ENTRIES</varname> variable. A
+ by using <varname>DESKTOP_ENTRIES</varname>. A
file named
<filename><replaceable>name</replaceable>.desktop</filename>
- will be created, installed, and added to the
+ will be created, installed, and added to
<filename>pkg-plist</filename> automatically. Syntax
is:</para>
@@ -1376,7 +1379,7 @@ USE_XORG= x11 xpm</programlisting>
after it has started. Programs that are not compatible
with startup notifications would never clear the indicator
(potentially confusing and infuriating the user), and
- should have <varname>StartupNotify</varname> set to
+ must have <varname>StartupNotify</varname> set to
<literal>false</literal> so the indicator is not shown at
all.</para>
@@ -1407,12 +1410,12 @@ USE_XORG= x11 xpm</programlisting>
<title>Ports That Require Qt</title>
<para>The Ports Collection provides support for Qt 4 and Qt 5
- frameworks with the
- <varname>USE_QT<replaceable>x</replaceable></varname>
- variable, where <replaceable>x</replaceable> is
+ frameworks with
+ <varname>USE_QT<replaceable>x</replaceable></varname>,
+ where <replaceable>x</replaceable> is
<literal>4</literal> or <literal>5</literal>.
- <varname>USE_QT<replaceable>x</replaceable></varname> should
- be set to the list of required Qt components (libraries,
+ Set <varname>USE_QT<replaceable>x</replaceable></varname>
+ to the list of required Qt components (libraries,
tools, plugins). The Qt 4 and Qt 5 frameworks are quite
similar. The main difference is the set of supported
components.</para>
@@ -1494,29 +1497,29 @@ PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \
<para>Some configure scripts do not support the arguments above.
To suppress modification of<varname>CONFIGURE_ENV</varname>
- and <varname>CONFIGURE_ARGS</varname>, set the
- <varname>QT_NONSTANDARD</varname> variable.</para>
+ and <varname>CONFIGURE_ARGS</varname>, set
+ <varname>QT_NONSTANDARD</varname>.</para>
</sect2>
<sect2 xml:id="qt-components">
<title>Component Selection</title>
<para>Individual Qt tool and library dependencies must be
- specified in the
- <varname>USE_QT<replaceable>x</replaceable></varname>
- variable. Every component can be suffixed with
+ specified in
+ <varname>USE_QT<replaceable>x</replaceable></varname>.
+ Every component can be suffixed with
<literal>_build</literal> or <literal>_run</literal>, the
- suffix indicating whether the component should be depended on
+ suffix indicating whether the dependency on the component is
at buildtime or runtime. If unsuffixed, the component will be
depended on at both build- and runtime. Usually, library
- components should be specified unsuffixed, tool components
- should be specified with the <literal>_build</literal> suffix
- and plugin components should be specified with the
+ components are specified unsuffixed, tool components
+ are mostly specified with the <literal>_build</literal> suffix
+ and plugin components are specified with the
<literal>_run</literal> suffix. The most commonly used
components are listed below (all available components are
listed in <varname>_USE_QT_ALL</varname>,
<varname>_USE_QT4_ONLY</varname>, and
- <varname>_USE_QT5_ONLY</varname> variables in
+ <varname>_USE_QT5_ONLY</varname> in
<filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>
<table frame="none" xml:id="using-qt-library-list">
@@ -1784,10 +1787,10 @@ USE_QT5= buildtools_build</programlistin
<para><emphasis>Missing additional include
paths.</emphasis> Many applications come with
system tray icon support, but neglect to look for
- includes and/or libraries in the X11 directories. You
- can tell <command>qmake</command> to add directories to
- the include and library search paths via the command
- line, for example:</para>
+ includes and/or libraries in the X11 directories. To add
+ directories to <command>qmake</command>'s
+ include and library search paths via the command
+ line, use:</para>
<programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
LIBS+=-L${LOCALBASE}/lib</programlisting>
@@ -1819,11 +1822,11 @@ USE_QT5= buildtools_build</programlistin
<varname>USE_KDE4</varname> to the list of required
components. <literal>_build</literal> and
<literal>_run</literal> suffixes can be used to force
- components dependency type (e.g.,
+ components dependency type (for example,
<literal>baseapps_run</literal>). If no suffix is set, a
- default dependency type will be used. If you want to force
+ default dependency type will be used. To force
both types, add the component twice with both suffixes
- (e.g., <literal>automoc4_build automoc4_run</literal>). The
+ (for example, <literal>automoc4_build automoc4_run</literal>). The
most commonly used components are listed below (up-to-date
components are documented at the top of
<filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para>
@@ -1995,7 +1998,7 @@ USE_QT5= buildtools_build</programlistin
determined through configure log.
<varname>USE_KDE4</varname> does not imply
<varname>USE_QT4</varname>. If a port requires some
- Qt 4 components, they should be specified in
+ Qt 4 components, specify them in
<varname>USE_QT4</varname>.</para>
<programlisting>USES= cmake:outsource
@@ -2011,14 +2014,14 @@ USE_QT4= moc_build qmake_build rcc_build
<sect2 xml:id="java-variables">
<title>Variable Definitions</title>
- <para>If your port needs a Java™ Development Kit
- (JDK™) to either build, run or even extract the
- distfile, then it should define
+ <para>If the port needs a Java™ Development Kit
+ (<acronym>JDK</acronym>™) to either build, run or even extract the
+ distfile, then define
<varname>USE_JAVA</varname>.</para>
- <para>There are several JDKs in the ports collection, from
- various vendors, and in several versions. If your port must
- use one of these versions, you can define which one. The
+ <para>There are several <acronym>JDK</acronym>s in the ports collection, from
+ various vendors, and in several versions. If the port must
+ use one of these versions, define which one. The
most current version, and &os; default is
<package role="port">java/openjdk6</package>.</para>
@@ -2037,7 +2040,7 @@ USE_QT4= moc_build qmake_build rcc_build
<tbody>
<row>
<entry><varname>USE_JAVA</varname></entry>
- <entry>Should be defined for the remaining variables
+ <entry>Define for the remaining variables
to have any effect.</entry>
</row>
@@ -2045,21 +2048,21 @@ USE_QT4= moc_build qmake_build rcc_build
<entry><varname>JAVA_VERSION</varname></entry>
<entry>List of space-separated suitable Java versions
for the port. An optional <literal>"+"</literal>
- allows you to specify a range of versions (allowed
+ allows specifying a range of versions (allowed
values:
<literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_OS</varname></entry>
- <entry>List of space-separated suitable JDK port
+ <entry>List of space-separated suitable <acronym>JDK</acronym> port
operating systems for the port (allowed values:
<literal>native linux</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_VENDOR</varname></entry>
- <entry>List of space-separated suitable JDK port
+ <entry>List of space-separated suitable <acronym>JDK</acronym> port
vendors for the port (allowed values:
<literal>freebsd bsdjava sun
openjdk</literal>).</entry>
@@ -2067,23 +2070,20 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVA_BUILD</varname></entry>
- <entry>When set, it means that the selected JDK port
- should be added to the build dependencies of the
- port.</entry>
+ <entry>When set, add the selected <acronym>JDK</acronym> port to the build
+ dependencies.</entry>
</row>
<row>
<entry><varname>JAVA_RUN</varname></entry>
- <entry>When set, it means that the selected JDK port
- should be added to the run dependencies of the
- port.</entry>
+ <entry>When set, add the selected <acronym>JDK</acronym> port to the run
+ dependencies.</entry>
</row>
<row>
<entry><varname>JAVA_EXTRACT</varname></entry>
- <entry>When set, it means that the selected JDK port
- should be added to the extract dependencies of the
- port.</entry>
+ <entry>When set, add the selected <acronym>JDK</acronym> port to the
+ extract dependencies.</entry>
</row>
</tbody>
</tgroup>
@@ -2106,61 +2106,61 @@ USE_QT4= moc_build qmake_build rcc_build
<tbody>
<row>
<entry><varname>JAVA_PORT</varname></entry>
- <entry>The name of the JDK port (e.g.,
- <literal>'java/openjdk6'</literal>).</entry>
+ <entry>The name of the <acronym>JDK</acronym> port (for example,
+ <literal>java/openjdk6</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VERSION</varname></entry>
- <entry>The full version of the JDK port (e.g.,
- <literal>'1.6.0'</literal>). If you only need the
- first two digits of this version number, use
+ <entry>The full version of the <acronym>JDK</acronym> port (for example,
+ <literal>1.6.0</literal>). Only the first two
+ digits of this version number are needed, use
<varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry>
</row>
<row>
<entry><varname>JAVA_PORT_OS</varname></entry>
- <entry>The operating system used by the JDK port
- (e.g., <literal>'native'</literal>).</entry>
+ <entry>The operating system used by the <acronym>JDK</acronym> port
+ (for example, <literal>'native'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VENDOR</varname></entry>
- <entry>The vendor of the JDK port (e.g.,
+ <entry>The vendor of the <acronym>JDK</acronym> port (for example,
<literal>'openjdk'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry>
<entry>Description of the operating system used by the
- JDK port (e.g.,
+ <acronym>JDK</acronym> port (for example,
<literal>'Native'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry>
- <entry>Description of the vendor of the JDK port
- (e.g., <literal>'OpenJDK BSD Porting
+ <entry>Description of the vendor of the <acronym>JDK</acronym> port
+ (for example, <literal>'OpenJDK BSD Porting
Team'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_HOME</varname></entry>
- <entry>Path to the installation directory of the JDK
- (e.g.,
+ <entry>Path to the installation directory of the <acronym>JDK</acronym>
+ (for example,
<filename>'/usr/local/openjdk6'</filename>).</entry>
</row>
<row>
<entry><varname>JAVAC</varname></entry>
- <entry>Path to the Java compiler to use (e.g.,
+ <entry>Path to the Java compiler to use (for example,
<filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry>
</row>
<row>
<entry><varname>JAR</varname></entry>
<entry>Path to the <command>jar</command> tool to use
- (e.g.,
+ (for example,
<filename>'/usr/local/openjdk6/bin/jar'</filename>
or
<filename>'/usr/local/bin/fastjar'</filename>).</entry>
@@ -2169,14 +2169,14 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>APPLETVIEWER</varname></entry>
<entry>Path to the <command>appletviewer</command>
- utility (e.g.,
+ utility (for example,
<filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry>
</row>
<row>
<entry><varname>JAVA</varname></entry>
<entry>Path to the <command>java</command> executable.
- Use this for executing Java programs (e.g.,
+ Use this for executing Java programs (for example,
<filename>'/usr/local/openjdk6/bin/java'</filename>).</entry>
</row>
@@ -2242,7 +2242,7 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVA_CLASSES</varname></entry>
- <entry>Path to the archive that contains the JDK class
+ <entry>Path to the archive that contains the <acronym>JDK</acronym> class
files,
<filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry>
</row>
@@ -2250,11 +2250,11 @@ USE_QT4= moc_build qmake_build rcc_build
</tgroup>
</table>
- <para>You may use the <literal>java-debug</literal> make
- target to get information for debugging your port. It will
- display the value of many of the forecited variables.</para>
+ <para>Use the <buildtarget>java-debug</buildtarget> make
+ target to get information for debugging the port. It will
+ display the value of many of the previously listed variables.</para>
- <para>Additionally, the following constants are defined so all
+ <para>Additionally, these constants are defined so all
Java ports may be installed in a consistent way:</para>
<table frame="none" xml:id="using-java-constants">
@@ -2278,7 +2278,7 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVAJARDIR</varname></entry>
- <entry>The directory where JAR files should be
+ <entry>The directory where JAR files is
installed. Default:
<filename>${JAVASHAREDIR}/classes</filename>.</entry>
</row>
@@ -2305,37 +2305,37 @@ USE_QT4= moc_build qmake_build rcc_build
<para>When the port is to be built using Apache Ant, it has to
define <varname>USE_ANT</varname>. Ant is thus considered
to be the sub-make command. When no
- <literal>do-build</literal> target is defined by the port, a
- default one will be set that simply runs Ant according to
+ <buildtarget>do-build</buildtarget> target is defined by the port, a
+ default one will be set that runs Ant according to
<varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname>
and <varname>ALL_TARGET</varname>. This is similar to the
- <varname>USES= gmake</varname> mechanism, which is
+ <literal>USES= gmake</literal> mechanism, which is
documented in <xref linkend="building"/>.</para>
</sect2>
<sect2 xml:id="java-best-practices">
<title>Best Practices</title>
- <para>When porting a Java library, your port should install
+ <para>When porting a Java library, the port has to install
the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and
everything else under
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for
- the documentation, see below). In order to reduce the
- packing file size, you may reference the JAR file(s)
- directly in the <filename>Makefile</filename>. Just use the
- following statement (where <filename>myport.jar</filename>
+ the documentation, see below). To reduce the
+ packing file size, reference the JAR file(s)
+ directly in the <filename>Makefile</filename>. Use this
+ statement (where <filename><replaceable>myport</replaceable>.jar</filename>
is the name of the JAR file installed as part of the
port):</para>
- <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
+ <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/<replaceable>myport</replaceable>.jar</programlisting>
<para>When porting a Java application, the port usually
installs everything under a single directory (including its
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-head
mailing list