docs/182872: [patch] add updated iconv information to the porter's handbook.

Guido Falsi madpilot at FreeBSD.org
Thu Oct 10 10:00:00 UTC 2013


>Number:         182872
>Category:       docs
>Synopsis:       [patch] add updated iconv information to the porter's handbook.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Oct 10 10:00:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Guido Falsi
>Release:        FreeBSD 9.2-STABLE amd64
>Organization:
none
>Environment:
System: FreeBSD micro.madpilot.net 9.2-STABLE FreeBSD 9.2-STABLE #22 r255995: Wed Oct 2 22:15:55 CEST 2013 root at micro.madpilot.net:/usr/obj/usr/src/sys/MICRO amd64

>Description:

After r254273 in head the port's system has been modified to use the native iconv implementation.

The iconv USES was modified to allow this and new variables have been created.

This patch adds information about this to the handbook.

>How-To-Repeat:
>Fix:

Index: en_US.ISO8859-1/books/porters-handbook/book.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/book.xml	(revision 42923)
+++ en_US.ISO8859-1/books/porters-handbook/book.xml	(working copy)
@@ -9356,6 +9356,134 @@
       </sect2>
     </sect1>
 
+    <sect1 id="using-iconv">
+      <title>Using <command>iconv</command></title>
+
+      <para>After r254273 FreeBSD 10-CURRENT and newer have a native
+	iconv implmentation.  On previous versions the <filename
+	role="package">converters/libiconv</filename> port was used
+	as the default implementation.</para>
+
+      <para>If your software uses the iconv functionality, define
+	<literal>USES=iconv</literal>.  On OS versions before
+	r254273, without a native iconv implementation, a dependency
+	on <filename role="package">converters/libiconv</filename>
+	will be added.</para>
+
+      <para>The <filename>iconv.mk</filename> USES file defines the
+	following variables you can use in your port:</para>
+
+      <informaltable frame="none" pgwide="0">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Variable name</entry>
+	      <entry>Purpose</entry>
+	      <entry>Value with base before r254273</entry>
+	      <entry>Value with base after r254273</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><makevar>ICONV_CMD</makevar></entry>
+	      <entry>Where the <command>iconv</command> binary
+		resides</entry>
+	      <entry>${LOCALBASE}/bin/iconv</entry>
+	      <entry>/usr/bin/iconv</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>ICONV_LIB</makevar></entry>
+	      <entry>ld argument to link to libiconv (if needed)</entry>
+	      <entry>-liconv</entry>
+	      <entry>(empty)</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>ICONV_PREFIX</makevar></entry>
+	      <entry>Where the iconv implementation resides (useful
+		for configure scripts)</entry>
+	      <entry>${LOCALBASE}</entry>
+	      <entry>/usr</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>ICONV_CONFIGURE_ARG</makevar></entry>
+	      <entry>Preconstructed configure argument for
+		configure scripts</entry>
+	      <entry>--with-libiconv-prefix=${LOCALBASE}</entry>
+	      <entry>(empty)</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>ICONV_CONFIGURE_BASE</makevar></entry>
+	      <entry>Preconstructed configure argument for
+		configure scripts</entry>
+	      <entry>--with-libiconv=${LOCALBASE}</entry>
+	      <entry>(empty)</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para>The following two examples will automatically populate
+	the variables with the correct value or empty for systems
+	using iconv or native iconv respectively:</para>
+
+      <example id="iconv-simple-use">
+	<title>Simple iconv Usage</title>
+
+	<programlisting>USES=		iconv
+LDFLAGS+=	-L${LOCALBASE}/lib ${ICONV_LIB}</programlisting>
+      </example>
+
+      <example id="iconv-configure-use">
+	<title>iconv Usage With configure</title>
+
+	<programlisting>USES=		iconv
+CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting>
+      </example>
+
+      <para>Sometimes a software has some ld argument or search
+	path hardcoded in it's Makefile or configure script, such an
+	approach can be used to fix these:</para>
+
+      <example id="iconv-reinplace">
+	<title>Fixing Hardcoded -liconv</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 conditionally set some
+	other values or performing operations depending on the presence
+	or absence of the native iconv implementations. in such cases
+	you can do this by checking if the ICONV_LIB is empty; doing
+	this requires <filename>bsd.port.pre.mk</filename> to be
+	included:</para>
+
+      <example id="iconv-conditional">
+	<title>Setting Port make Variables Depending on Native iconv
+	  Availability</title>
+
+	<programlisting>USES=		iconv
+
+.include <bsd.port.pre.mk>
+
+post-patch:
+.if empty(ICONV_LIB)
+	@${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>
 
Index: en_US.ISO8859-1/books/porters-handbook/uses.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/uses.xml	(revision 42923)
+++ en_US.ISO8859-1/books/porters-handbook/uses.xml	(working copy)
@@ -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 iconv functions, from port
+    <filename role="package">converters/libiconv</filename> as
+    build-time and run-time dependency or from base system on
+    10-CURRENT after native iconv implementation has been committed
+    in r254273.  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>
>Release-Note:
>Audit-Trail:
>Unformatted:


More information about the freebsd-doc mailing list