Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 29 Oct 2013 01:38:53 +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: r43068 - head/en_US.ISO8859-1/books/porters-handbook
Message-ID:  <201310290138.r9T1crZB029643@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
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@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;&nbsp;
+	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;&nbsp;10-CURRENT
+		<svnref>254273</svnref> (2013-08-13)</entry>
+	      <entry>Value after &os;&nbsp;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 &lt;bsd.port.pre.mk&gt;
+
+post-patch:
+.if empty(ICONV_LIB)
+	# native iconv detected
+	@${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh
+.endif
+
+.include &lt;bsd.port.post.mk&gt;</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>



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310290138.r9T1crZB029643>