Bug 182872
| Summary: | [patch] add updated iconv information to the porter's handbook. | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Guido Falsi <madpilot> | ||||
| Component: | Books & Articles | Assignee: | Warren Block <wblock> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Guido Falsi
2013-10-10 11:00:00 UTC
Responsible Changed From-To: freebsd-doc->wblock Take. 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; + 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> _______________________________________________ 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" State Changed From-To: open->closed Committed modified version of supplied patch. Thanks! |