<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 &lt;bsd.port.post.mk&gt;</programlisting>

      </example>

    </sect1>