svn commit: r43068 - head/en_US.ISO8859-1/books/porters-handbook
Warren Block
wblock at FreeBSD.org
Tue Oct 29 01:38:54 UTC 2013
Author: wblock
Date: Tue Oct 29 01:38:53 2013
New Revision: 43068
URL: http://svnweb.freebsd.org/changeset/doc/43068
Log:
Add updated iconv information. Modified version of diff supplied with PR.
PR: docs/182872
Submitted by: Guido Falsi <madpilot at FreeBSD.org>
Modified:
head/en_US.ISO8859-1/books/porters-handbook/book.xml
head/en_US.ISO8859-1/books/porters-handbook/uses.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml Mon Oct 28 23:17:30 2013 (r43067)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Tue Oct 29 01:38:53 2013 (r43068)
@@ -9286,6 +9286,151 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR
</sect2>
</sect1>
+ <sect1 id="using-iconv">
+ <title>Using <command>iconv</command></title>
+
+ <para>After 2013-10-08 (<svnref>254273</svnref>), &os;
+ 10-CURRENT and newer versions have a native
+ <command>iconv</command> in the operating system. On earlier
+ versions,
+ <filename role="package">converters/libiconv</filename> was
+ used as a dependency.</para>
+
+ <para>For software that needs <command>iconv</command>, define
+ <literal>USES=iconv</literal>. &os; versions before
+ 10-CURRENT on 2013-08-13 (<svnref>254273</svnref>) do not have
+ a native <command>iconv</command>. On these earlier versions,
+ a dependency on
+ <filename role="package">converters/libiconv</filename> will
+ be added automatically.</para>
+
+ <para>When a port defines <literal>USES=iconv</literal>, these
+ variables will be available:</para>
+
+ <informaltable frame="none" pgwide="0">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable name</entry>
+ <entry>Purpose</entry>
+ <entry>Value before &os; 10-CURRENT
+ <svnref>254273</svnref> (2013-08-13)</entry>
+ <entry>Value after &os; 10-CURRENT
+ <svnref>254273</svnref> (2013-08-13)</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ICONV_CMD</makevar></entry>
+
+ <entry>Directory where the <command>iconv</command>
+ binary resides</entry>
+ <entry><literal>${LOCALBASE}/bin/iconv</literal></entry>
+ <entry><filename
+ class="directory">/usr/bin/iconv</filename></entry>
+ </row>
+
+ <row>
+ <entry><makevar>ICONV_LIB</makevar></entry>
+ <entry><command>ld</command> argument to link to
+ <filename>libiconv</filename> (if needed)</entry>
+ <entry><literal>-liconv</literal></entry>
+ <entry>(empty)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>ICONV_PREFIX</makevar></entry>
+ <entry>Directory where the <command>iconv</command>
+ implementation resides (useful for configure
+ scripts)</entry>
+ <entry><literal>${LOCALBASE}</literal></entry>
+ <entry><filename
+ class="directory">/usr</filename></entry>
+ </row>
+
+ <row>
+ <entry><makevar>ICONV_CONFIGURE_ARG</makevar></entry>
+ <entry>Preconstructed configure argument for
+ configure scripts</entry>
+ <entry><literal>--with-libiconv-prefix=${LOCALBASE}</literal></entry>
+ <entry>(empty)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>ICONV_CONFIGURE_BASE</makevar></entry>
+ <entry>Preconstructed configure argument for
+ configure scripts</entry>
+ <entry><literal>--with-libiconv=${LOCALBASE}</literal></entry>
+ <entry>(empty)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>These two examples automatically populate the variables
+ with the correct value for systems using
+ <filename role="package">converters/libiconv</filename> or the
+ native <command>iconv</command> respectively:</para>
+
+ <example id="iconv-simple-use">
+ <title>Simple <command>iconv</command> Usage</title>
+
+ <programlisting>USES= iconv
+LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting>
+ </example>
+
+ <example id="iconv-configure-use">
+ <title><command>iconv</command> Usage with
+ <command>configure</command></title>
+
+ <programlisting>USES= iconv
+CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting>
+ </example>
+
+ <para>As shown above, <makevar>ICONV_LIB</makevar> is empty when
+ a native <command>iconv</command> is present. This can be
+ used to detect the native <command>iconv</command> and respond
+ appropriately.</para>
+
+ <para>Sometimes a program has an <command>ld</command> argument
+ or search path hardcoded in a <filename>Makefile</filename> or
+ configure script. This approach can be used to solve that
+ problem:</para>
+
+ <example id="iconv-reinplace">
+ <title>Fixing Hardcoded <literal>-liconv</literal></title>
+
+ <programlisting>USES= iconv
+
+post-patch:
+ @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile</programlisting>
+ </example>
+
+ <para>In some cases it is necessary to set alternate values or
+ perform operations depending on whether there is a native
+ <command>iconv</command>.
+ <filename>bsd.port.pre.mk</filename> must be included before
+ testing the value of <makevar>ICONV_LIB</makevar>:</para>
+
+ <example id="iconv-conditional">
+ <title>Checking for Native <command>iconv</command>
+ Availability</title>
+
+ <programlisting>USES= iconv
+
+.include <bsd.port.pre.mk>
+
+post-patch:
+.if empty(ICONV_LIB)
+ # native iconv detected
+ @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh
+.endif
+
+.include <bsd.port.post.mk></programlisting>
+ </example>
+ </sect1>
+
<sect1 id="using-xfce">
<title>Using Xfce</title>
Modified: head/en_US.ISO8859-1/books/porters-handbook/uses.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses.xml Mon Oct 28 23:17:30 2013 (r43067)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses.xml Tue Oct 29 01:38:53 2013 (r43068)
@@ -106,10 +106,18 @@
<row>
<entry><literal>iconv</literal></entry>
- <entry>(none)</entry>
- <entry>Implies that the port uses <filename
- role="package">converters/libiconv</filename> as build-time and
- run-time dependency.</entry>
+ <entry>(none), <literal>lib</literal>, <literal>build</literal>,
+ <literal>patch</literal></entry>
+ <entry>Implies that the port uses <command>iconv</command> functions, either from the port
+ <filename role="package">converters/libiconv</filename> as
+ a build-time and run-time dependency, or from the base system on
+ 10-CURRENT after a native <command>iconv</command> was committed
+ in <svnref>254273</svnref>. By default, with no arguments or with the
+ <literal>lib</literal> argument, implies <command>iconv</command>
+ with build-time and run-time dependencies, <literal>build</literal>
+ implies a build-time dependency, and <literal>patch</literal>
+ implies a patch-time dependency. For more information see
+ <xref linkend="using-iconv"/>.</entry>
</row>
<row>
More information about the svn-doc-all
mailing list