From mad@micro.madpilot.net  Thu Oct 10 09:53:03 2013
Return-Path: <mad@micro.madpilot.net>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1])
	(using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by hub.freebsd.org (Postfix) with ESMTP id E5136C0B
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 10 Oct 2013 09:53:02 +0000 (UTC)
	(envelope-from mad@micro.madpilot.net)
Received: from micro.madpilot.net (micro.madpilot.net [88.149.173.206])
	by mx1.freebsd.org (Postfix) with ESMTP id 8787B2DF1
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 10 Oct 2013 09:53:02 +0000 (UTC)
Received: from micro.madpilot.net (localhost [127.0.0.1])
	by micro.madpilot.net (Postfix) with ESMTP id 3cwSK33vYcz6K
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 10 Oct 2013 11:52:55 +0200 (CEST)
Received: from micro.madpilot.net ([127.0.0.1])
	by micro.madpilot.net (micro.madpilot.net [127.0.0.1]) (amavisd-new, port 10026)
	with ESMTP id 3Smicz2pofPI for <FreeBSD-gnats-submit@freebsd.org>;
	Thu, 10 Oct 2013 11:52:52 +0200 (CEST)
Received: by micro.madpilot.net (Postfix, from userid 1000)
	id 3cwSK03qZBz6J; Thu, 10 Oct 2013 11:52:52 +0200 (CEST)
Message-Id: <3cwSK03qZBz6J@micro.madpilot.net>
Date: Thu, 10 Oct 2013 11:52:52 +0200 (CEST)
From: Guido Falsi <madpilot@FreeBSD.org>
Reply-To: Guido Falsi <madpilot@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] add updated iconv information to the porter's handbook.
X-Send-Pr-Version: 3.114
X-GNATS-Notify:

>Number:         182872
>Category:       docs
>Synopsis:       [patch] add updated iconv information to the porter's handbook.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Oct 10 10:00:00 UTC 2013
>Closed-Date:    Tue Oct 29 01:39:53 UTC 2013
>Last-Modified:  Tue Oct 29 01:40:00 UTC 2013
>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@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 &lt;bsd.port.pre.mk&gt;
+
+post-patch:
+.if empty(ICONV_LIB)
+	@${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>
 
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:
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Mon Oct 28 18:55:59 UTC 2013 
Responsible-Changed-Why:  
Take. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=182872 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Tue Oct 29 01:39:27 UTC 2013 
State-Changed-Why:  
Committed modified version of supplied patch.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=182872 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/182872: commit references a PR
Date: Tue, 29 Oct 2013 01:39:00 +0000 (UTC)

 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>
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
>Unformatted:
