svn commit: r47881 - head/en_US.ISO8859-1/books/porters-handbook/special
Warren Block
wblock at FreeBSD.org
Thu Dec 17 02:16:47 UTC 2015
Author: wblock
Date: Thu Dec 17 02:16:45 2015
New Revision: 47881
URL: https://svnweb.freebsd.org/changeset/doc/47881
Log:
Whitespace-only fixes, translators please ignore.
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 Thu Dec 17 01:59:30 2015 (r47880)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Thu Dec 17 02:16:45 2015 (r47881)
@@ -79,16 +79,15 @@
<programlisting>${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
<para>The source path
- <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
+ <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
- <varname>STAGEDIR</varname> to
- their destination, by default
+ <varname>STAGEDIR</varname> to their destination, by default
<filename>/boot/modules</filename>.</para>
</sect1>
@@ -679,16 +678,17 @@ IGNORE= may not be redistributed because
<literal>-Os -DNDEBUG</literal> correspondingly. The
lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is
exported to <varname>PLIST_SUB</varname> and must be
- used if the port installs <filename><replaceable>*</replaceable>.cmake</filename>
+ 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>. 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
+ 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>. 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
removed from those files.</para>
<para>Most <application>CMake</application>-based projects
@@ -816,7 +816,8 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp
</sect2>
<sect2 xml:id="using-libtool">
- <title><command>libtool</command> and <command>libtoolize</command></title>
+ <title><command>libtool</command> and
+ <command>libtoolize</command></title>
<para>Ports shipping with their own copy of libtool (search for
a file named ltmain.sh) need to have
@@ -950,13 +951,13 @@ GNU_CONFIGURE= yes</programlisting>
<sect2 xml:id="using-gettext-optional">
<title>Optional Usage</title>
- <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, 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>
+ <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, 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
@@ -1091,8 +1092,8 @@ PLIST_SUB+= NLS="@comment "
<row>
<entry><varname>PERL_VERSION</varname></entry>
- <entry>The full version of Perl
- installed (for example, <literal>5.8.9</literal>).</entry>
+ <entry>The full version of Perl installed (for example,
+ <literal>5.8.9</literal>).</entry>
</row>
<row>
@@ -1111,8 +1112,8 @@ PLIST_SUB+= NLS="@comment "
<row>
<entry><varname>PERL_PORT</varname></entry>
- <entry>Name of the Perl port that is
- installed (for example, <literal>perl5</literal>).</entry>
+ <entry>Name of the Perl port that is installed (for
+ example, <literal>perl5</literal>).</entry>
</row>
<row>
@@ -1337,8 +1338,8 @@ USE_XORG= x11 xpm</programlisting>
Files</title>
<para>Ports that include predefined
- <filename><replaceable>*</replaceable>.desktop</filename> must
- include those files in <filename>pkg-plist</filename>
+ <filename><replaceable>*</replaceable>.desktop</filename>
+ must include those files in <filename>pkg-plist</filename>
and install them in the
<filename>$LOCALBASE/share/applications</filename>
directory. The <link
@@ -2668,10 +2669,10 @@ USE_QT5= buildtools_build</programlistin
<literal>_run</literal> suffixes can be used to force
components dependency type (for example,
<literal>baseapps_run</literal>). If no suffix is set, a
- default dependency type will be used. To force
- both types, add the component twice with both suffixes
- (for example, <literal>automoc4_build automoc4_run</literal>). The
- most commonly used components are listed below (up-to-date
+ default dependency type will be used. To force both types,
+ add the component twice with both suffixes (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>
@@ -2859,14 +2860,14 @@ USE_QT4= moc_build qmake_build rcc_build
<title>Variable Definitions</title>
<para>If the port needs a Java™ Development Kit
- (<acronym>JDK</acronym>™) to either build, run or even extract the
- distfile, then define
+ (<acronym>JDK</acronym>™) to either build, run or even
+ extract the distfile, then define
<varname>USE_JAVA</varname>.</para>
- <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
+ <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>
<table frame="none" xml:id="using-java-variables">
@@ -2899,35 +2900,37 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVA_OS</varname></entry>
- <entry>List of space-separated suitable <acronym>JDK</acronym> port
- operating systems for the port (allowed values:
+ <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 <acronym>JDK</acronym> port
- vendors for the port (allowed values:
+ <entry>List of space-separated suitable
+ <acronym>JDK</acronym> port vendors for the port
+ (allowed values:
<literal>freebsd bsdjava sun
openjdk</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_BUILD</varname></entry>
- <entry>When set, add the selected <acronym>JDK</acronym> port to the build
- dependencies.</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, add the selected <acronym>JDK</acronym> port to the run
- dependencies.</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, add the selected <acronym>JDK</acronym> port to the
- extract dependencies.</entry>
+ <entry>When set, add the selected <acronym>JDK</acronym>
+ port to the extract dependencies.</entry>
</row>
</tbody>
</tgroup>
@@ -2950,28 +2953,30 @@ USE_QT4= moc_build qmake_build rcc_build
<tbody>
<row>
<entry><varname>JAVA_PORT</varname></entry>
- <entry>The name of the <acronym>JDK</acronym> port (for example,
- <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 <acronym>JDK</acronym> port (for example,
- <literal>1.6.0</literal>). Only the first two
- digits of this version number are needed, 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 <acronym>JDK</acronym> port
- (for example, <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 <acronym>JDK</acronym> port (for example,
- <literal>'openjdk'</literal>).</entry>
+ <entry>The vendor of the <acronym>JDK</acronym> port
+ (for example, <literal>'openjdk'</literal>).</entry>
</row>
<row>
@@ -2983,15 +2988,16 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry>
- <entry>Description of the vendor of the <acronym>JDK</acronym> port
- (for example, <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 <acronym>JDK</acronym>
- (for example,
+ <entry>Path to the installation directory of the
+ <acronym>JDK</acronym> (for example,
<filename>'/usr/local/openjdk6'</filename>).</entry>
</row>
@@ -3086,8 +3092,8 @@ USE_QT4= moc_build qmake_build rcc_build
<row>
<entry><varname>JAVA_CLASSES</varname></entry>
- <entry>Path to the archive that contains the <acronym>JDK</acronym> class
- files,
+ <entry>Path to the archive that contains the
+ <acronym>JDK</acronym> class files,
<filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry>
</row>
</tbody>
@@ -3096,7 +3102,8 @@ USE_QT4= moc_build qmake_build rcc_build
<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>
+ display the value of many of the previously listed
+ variables.</para>
<para>Additionally, these constants are defined so all
Java ports may be installed in a consistent way:</para>
@@ -3147,14 +3154,14 @@ USE_QT4= moc_build qmake_build rcc_build
<title>Building with Ant</title>
<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
- <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
- <literal>USES= gmake</literal> mechanism, which is
- documented in <xref linkend="building"/>.</para>
+ define <varname>USE_ANT</varname>. Ant is thus considered to
+ be the sub-make command. When no
+ <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
+ <literal>USES= gmake</literal> mechanism, which is documented
+ in <xref linkend="building"/>.</para>
</sect2>
<sect2 xml:id="java-best-practices">
@@ -3164,11 +3171,11 @@ USE_QT4= moc_build qmake_build rcc_build
the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and
everything else under
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for
- 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
+ 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%%/<replaceable>myport</replaceable>.jar</programlisting>
@@ -3212,18 +3219,18 @@ do-install:
@cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting>
<para>Regardless of the type of port (library or
- application), the additional documentation is
- installed in the
- <link linkend="install-documentation">same location</link>
- as for any other port. The JavaDoc tool is known to produce
- a different set of files depending on the version of the <acronym>JDK</acronym>
- that is used. For ports that do not enforce the use of a
- particular <acronym>JDK</acronym>, it is therefore a complex task to specify
- the packing list (<filename>pkg-plist</filename>). This is
- one reason why porters are strongly encouraged to use
- <varname>PORTDOCS</varname>. Moreover, even if the
- set of files that will be generated by
- <command>javadoc</command> can be predicted, the size of the resulting
+ application), the additional documentation is installed in the
+ <link linkend="install-documentation">same location</link> as
+ for any other port. The JavaDoc tool is known to produce a
+ different set of files depending on the version of the
+ <acronym>JDK</acronym> that is used. For ports that do not
+ enforce the use of a particular <acronym>JDK</acronym>, it is
+ therefore a complex task to specify the packing list
+ (<filename>pkg-plist</filename>). This is one reason why
+ porters are strongly encouraged to use
+ <varname>PORTDOCS</varname>. Moreover, even if the set of
+ files that will be generated by <command>javadoc</command> can
+ be predicted, the size of the resulting
<filename>pkg-plist</filename> advocates for the use of
<varname>PORTDOCS</varname>.</para>
@@ -3257,11 +3264,11 @@ do-install:
on the &a.java;.</para>
<para>Although there is a <literal>java</literal> category for
- PRs, it refers to the <acronym>JDK</acronym> porting effort from the &os; Java
- project. Therefore, submit the Java port in the
- <literal>ports</literal> category as for any other port,
- unless the issue is related to
- either a <acronym>JDK</acronym> implementation or
+ PRs, it refers to the <acronym>JDK</acronym> porting effort
+ from the &os; Java project. Therefore, submit the Java port
+ in the <literal>ports</literal> category as for any other
+ port, unless the issue is related to either a
+ <acronym>JDK</acronym> implementation or
<filename>bsd.java.mk</filename>.</para>
<para>Similarly, there is a defined policy regarding the
@@ -3604,18 +3611,18 @@ SOCKETS_USE= PHP=sockets
<tbody>
<row>
<entry><varname>USES=python</varname></entry>
- <entry>The port needs Python. The minimal required version
- can be specified with values such as
- <literal>2.7+</literal>. Version ranges can also be
- specified by separating two version numbers with a
- dash: <literal>USES=python:3.2-3.3</literal></entry>
+ <entry>The port needs Python. The minimal required
+ version can be specified with values such as
+ <literal>2.7+</literal>. Version ranges can also be
+ specified by separating two version numbers with a dash:
+ <literal>USES=python:3.2-3.3</literal></entry>
</row>
<row>
<entry><varname>USE_PYTHON=distutils</varname></entry>
<entry>Use Python distutils for configuring, compiling,
- and installing. This is required when the port comes
- with <filename>setup.py</filename>. This overrides
+ and installing. This is required when the port comes
+ with <filename>setup.py</filename>. This overrides
the <buildtarget>do-build</buildtarget> and
<buildtarget>do-install</buildtarget> targets and may
also override <buildtarget>do-configure</buildtarget>
@@ -3625,22 +3632,23 @@ SOCKETS_USE= PHP=sockets
<row>
<entry><varname>USE_PYTHON=autoplist</varname></entry>
- <entry>Create the packaging list automatically. This also requires
- <literal>USE_PYTHON=distutils</literal> to be set.
- </entry>
- </row>
-
- <row>
- <entry><varname>USE_PYTHON=concurrent</varname></entry>
- <entry>The port will use an unique prefix, typically
- <literal>PYTHON_PKGNAMEPREFIX</literal> for certain directories, such
- as <literal>EXAMPLESDIR</literal> and <literal>DOCSDIR</literal> and
- also will append a suffix, the python version from
- <literal>PYTHON_VER</literal>, to binaries and scripts to be
- installed. This allows ports to be installed for different Python
- versions at the same time, which otherwise would install conflicting
- files.</entry>
- </row>
+ <entry>Create the packaging list automatically. This also
+ requires <literal>USE_PYTHON=distutils</literal> to be
+ set.</entry>
+ </row>
+
+ <row>
+ <entry><varname>USE_PYTHON=concurrent</varname></entry>
+ <entry>The port will use an unique prefix, typically
+ <literal>PYTHON_PKGNAMEPREFIX</literal> for certain
+ directories, such as <literal>EXAMPLESDIR</literal> and
+ <literal>DOCSDIR</literal> and also will append a
+ suffix, the python version from
+ <literal>PYTHON_VER</literal>, to binaries and scripts
+ to be installed. This allows ports to be installed for
+ different Python versions at the same time, which
+ otherwise would install conflicting files.</entry>
+ </row>
<row>
<entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry>
@@ -3699,12 +3707,11 @@ SOCKETS_USE= PHP=sockets
<para>A complete list of available variables can be found in
<filename>/usr/ports/Mk/Uses/python.mk</filename>.</para>
+ <example xml:id="python-Makefile">
+ <title>Makefile for a Simple <application>Python</application>
+ Module</title>
- <example xml:id="python-Makefile">
- <title>Makefile for a Simple <application>Python</application>
- Module</title>
-
- <programlisting>PORTNAME= sample
+ <programlisting>PORTNAME= sample
PORTVERSION= 1.2.3
CATEGORIES= devel
@@ -3715,7 +3722,7 @@ USES= python
USE_PYTHON= autoplist distutils
.include <bsd.port.mk></programlisting>
- </example>
+ </example>
<para>Some Python applications claim to have
<varname>DESTDIR</varname> support (which would be required
@@ -5199,8 +5206,8 @@ USE_XFCE= libexo libmenu libutil panel</
<row>
<entry><varname>USE_PGSQL</varname></entry>
- <entry>Retired in favor of
- <link linkend="uses-pgsql"><literal>USES=pgsql</literal></link>.</entry>
+ <entry>Retired in favor of <link
+ linkend="uses-pgsql"><literal>USES=pgsql</literal></link>.</entry>
</row>
<row>
@@ -5340,10 +5347,11 @@ run_rc_command "$1"</programlisting>
<procedure>
<step>
<para>If this is a new file, does it have a
- <filename>.sh</filename> extension? If so, that
- must be changed to just <filename><replaceable>file</replaceable>.in</filename>
- since <filename>rc.d</filename> files may not end
- with that extension.</para>
+ <filename>.sh</filename> extension? If so, that must be
+ changed to just
+ <filename><replaceable>file</replaceable>.in</filename>
+ since <filename>rc.d</filename> files may not end with
+ that extension.</para>
</step>
<step>
@@ -5399,8 +5407,9 @@ run_rc_command "$1"</programlisting>
<command>perl</command>, <command>python</command>, or
<command>ruby</command>, make certain that
<varname>command_interpreter</varname> is set
- appropriately, for example, for <application>Perl</application>,
- by adding <literal>PERL=${PERL}</literal> to
+ appropriately, for example, for
+ <application>Perl</application>, by adding
+ <literal>PERL=${PERL}</literal> to
<varname>SUB_LIST</varname> and using
<literal>%%PERL%%</literal>. Otherwise,</para>
@@ -5489,12 +5498,12 @@ run_rc_command "$1"</programlisting>
<sect1 xml:id="users-and-groups">
<title>Adding Users and Groups</title>
- <para>Some ports require a particular user account to be present, usually
- for daemons that run as that user. For these ports, choose a
- <emphasis>unique</emphasis> UID from 50 to 999 and register it in
- <filename>ports/UIDs</filename> (for users) and
- <filename>ports/GIDs</filename> (for groups). The unique identification
- should be the same for users and groups.</para>
+ <para>Some ports require a particular user account to be present,
+ usually for daemons that run as that user. For these ports,
+ choose a <emphasis>unique</emphasis> UID from 50 to 999 and
+ register it in <filename>ports/UIDs</filename> (for users) and
+ <filename>ports/GIDs</filename> (for groups). The unique
+ identification should be the same for users and groups.</para>
<para>Please include a patch against these two files when
requiring a new user or group to be created for the
More information about the svn-doc-all
mailing list