Date: Thu, 17 Dec 2015 02:16:45 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47881 - head/en_US.ISO8859-1/books/porters-handbook/special Message-ID: <201512170216.tBH2GjXi067342@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201512170216.tBH2GjXi067342>