Date: Mon, 13 Nov 2006 19:10:39 -0300 From: "Alejandro Pulver" <alepulver@FreeBSD.org> To: "FreeBSD gnats submit" <FreeBSD-gnats-submit@FreeBSD.org> Subject: docs/105494: [PATCH] PH: rewrite WxWidgets entry Message-ID: <1163455839.24155@phobos.mars.bsd> Resent-Message-ID: <200611132220.kADMK6Kk057271@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 105494
>Category: docs
>Synopsis: [PATCH] PH: rewrite WxWidgets entry
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: update
>Submitter-Id: current-users
>Arrival-Date: Mon Nov 13 22:20:06 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator: Alejandro Pulver
>Release: FreeBSD 6.1-RELEASE-p1 i386
>Organization:
>Environment:
System: FreeBSD 6.1-RELEASE-p1 #3: Mon Jun 19 14:49:35 ART 2006
root@phobos.mars.bsd:/usr/obj/usr/src/sys/ATHLON-PHOBOS
>Description:
- Rewrite WxWidgets entry.
>How-To-Repeat:
>Fix:
--- patch_wx.diff begins here ---
Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.765
diff -u -r1.765 book.sgml
--- book.sgml 3 Nov 2006 21:04:09 -0000 1.765
+++ book.sgml 12 Nov 2006 14:12:29 -0000
@@ -6182,85 +6182,580 @@
</sect1>
<sect1 id="using-wx">
- <title>Using wxWidgets</title>
+ <title>Using <application>WxWidgets</application></title>
- <para>If your port uses <application>wxWidgets</application>
- cross-platform toolkit, define <literal>USE_WX</literal>.
- A specific version must be requested by setting
- <literal>USE_WX=2.6</literal>. Ranges (<literal>2.4-2.6</literal>)
- and partial ranges (<literal>-2.4</literal>, <literal>2.6+</literal>)
- are also possible.</para>
-
- <para>List of required wxWidgets components can be set as
- <makevar>WX_COMPS</makevar>. Unless specified otherwise, port will
- depend on wxWidgets library (<literal>wx</literal>). Available
- components are:</para>
-
- <table frame="none">
- <title>Possible values for <makevar>WX_COMPS</makevar></title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Value</entry>
-
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>wx</literal></entry>
-
- <entry>wxWidget libraries</entry>
- </row>
-
- <row>
- <entry><literal>contrib</literal></entry>
-
- <entry>wxWidget contributed libraries</entry>
- </row>
-
- <row>
- <entry><literal>python</literal></entry>
-
- <entry>wxPython</entry>
- </row>
-
- <row>
- <entry><literal>mozilla</literal></entry>
-
- <entry>wxMozilla (only available for 2.4)</entry>
- </row>
-
- <row>
- <entry><literal>svg</literal></entry>
-
- <entry>wxSVG (only available for 2.6)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>If locating wxWidget libraries needs a configure argument in
- addition to the <makevar>WX_CONFIG</makevar> variable, define
- <makevar>WX_CONF_ARGS</makevar> in your port. Possible values
- are <literal>absolute</literal> resulting in
- <literal>--with-wx-config=${WX_CONFIG}</literal>, and
- <literal>relative</literal> resulting in
- <literal>--with-wx=${X11BASE} --with-wx-config=${WX_CONFIG}</literal>
- being added to configure script arguments.</para>
-
- <para>Define <literal>WX_UNICODE=yes</literal> if your port needs
- the Unicode version of the wxWidgets libraries.</para>
-
- <para>Example of port requiring Unicode versions of wxWidgets 2.6 and
- contrib libraries:</para>
-
- <programlisting>USE_WX= 2.6
-WX_COMPS= wx contrib
-WX_UNICODE= yes</programlisting>
+ <para>This section describes the status of the
+ <application>WxWidgets</application> libraries in the ports tree and
+ its integration with the ports system.</para>
+
+ <sect2 id="wx-introduction">
+ <title>Introduction</title>
+
+ <para>There are many versions of the
+ <application>WxWidgets</application> libraries which conflict
+ between them (install files under the same name). In the ports tree
+ this problem has been solved by installing each version under a
+ different name using version number suffixes.</para>
+
+ <para>The obvious disadvantage of this is that each application has to
+ be modified to found the expected version. Fortunately most of the
+ applications call the <command>wx-config</command> script to
+ determine the necessary compiler and linker flags, which is named
+ differently for all the available versions, and the majority of them
+ also have a variable or accept a parameter to allow modifying
+ it. Otherwise the applications could be modified to use one of
+ them.</para>
+ </sect2>
+
+ <sect2 id="wx-version">
+ <title>Version selection</title>
+
+ <para>To make your port use a specific version of
+ <application>WxWidgets</application> there are two variables
+ available for defining (if only one is defined the other will be set
+ to a default value):</para>
+
+ <table id="wx-ver-sel-table" frame="none">
+ <title>Variables to select <application>WxWidgets</application>
+ versions</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+
+ <entry>Description</entry>
+
+ <entry>Default value</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>USE_WX</makevar></entry>
+
+ <entry>List of versions the port can use</entry>
+
+ <entry>All available versions</entry>
+ </row>
+
+ <row>
+ <entry><makevar>USE_WX_NOT</makevar></entry>
+
+ <entry>List of versions the port can not use</entry>
+
+ <entry>None</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The following is a list of available
+ <application>WxWidgets</application> versions and the corresponding
+ port in the tree:</para>
+
+ <table frame="none">
+ <title>Available <application>WxWidgets</application>
+ versions</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Version</entry>
+
+ <entry>Port</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>2.4</literal></entry>
+
+ <entry><filename
+ role="package">x11-toolkits/wxgtk24</filename></entry>
+ </row>
+
+ <row>
+ <entry><literal>2.6</literal></entry>
+
+ <entry><filename
+ role="package">x11-toolkits/wxgtk26</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para>The <literal>2.6</literal> version also comes in Unicode and
+ is installed by the slave port <filename
+ role="package">x11-toolkits/wxgtk26-unicode</filename>, but this
+ can be handled with variables (see <xref
+ linkend="wx-unicode">).</para>
+ </note>
+
+ <para>The variables in <xref linkend="wx-ver-sel-table"> can be set
+ to one or more of the following combinations separated by
+ spaces:</para>
+
+ <table frame="none">
+ <title><application>WxWidgets</application> version
+ specifications</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Description</entry>
+
+ <entry>Example</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Single version</entry>
+
+ <entry><literal>2.4</literal></entry>
+ </row>
+
+ <row>
+ <entry>Ascending range</entry>
+
+ <entry><literal>2.4+</literal></entry>
+ </row>
+
+ <row>
+ <entry>Descending range</entry>
+
+ <entry><literal>2.6-</literal></entry>
+ </row>
+
+ <row>
+ <entry>Full range (must be ascending)</entry>
+
+ <entry><literal>2.4-2.6</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>There are also some variables to select the preferred versions
+ from the available ones. They can be set to a list of versions, the
+ first ones will have higher priority.</para>
+
+ <table frame="none">
+ <title>Variables to select preferred
+ <application>WxWidgets</application> versions</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Designed for</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>WANT_WX_VER</makevar></entry>
+
+ <entry>the port</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_WX_VER</makevar></entry>
+
+ <entry>the user</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect2 id="wx-components">
+ <title>Component selection</title>
+
+ <para>There are other applications that, while not being
+ <application>WxWidgets</application> libraries, are related to them.
+ These applications can be specified in the
+ <makevar>WX_COMPS</makevar> variable. The following components are
+ available:</para>
+
+ <table frame="none">
+ <title>Available <application>WxWidgets</application>
+ components</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+
+ <entry>Version restriction</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>wx</literal></entry>
+
+ <entry>main library</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry><literal>contrib</literal></entry>
+
+ <entry>contributed libraries</entry>
+
+ <entry><literal>none</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>python</literal></entry>
+
+ <entry><application>WxPython</application>
+ (<application>Python</application> bindings)</entry>
+
+ <entry><literal>none</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>mozilla</literal></entry>
+
+ <entry><application>WxMozilla</application></entry>
+
+ <entry><literal>2.4</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>svg</literal></entry>
+
+ <entry><application>WxSVG</application></entry>
+
+ <entry><literal>2.6</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The dependency type added when you select each component can be
+ manually specified by adding a suffix separated by a
+ <literal>:</literal>, or a default value will be used. The available
+ dependency types are:</para>
+
+ <table frame="none">
+ <title>Available <application>WxWidgets</application> dependency
+ types</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>build</literal></entry>
+
+ <entry>Component is required for building, equivalent to
+ <makevar>BUILD_DEPENDS</makevar></entry>
+ </row>
+
+ <row>
+ <entry><literal>run</literal></entry>
+
+ <entry>Component is required for running, equivalent to
+ <makevar>RUN_DEPENDS</makevar></entry>
+ </row>
+
+ <row>
+ <entry><literal>lib</literal></entry>
+
+ <entry>Component is required for building and running,
+ equivalent to <makevar>LIB_DEPENDS</makevar>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The default values for the components are detailed in the
+ following table:</para>
+
+ <table frame="none">
+ <title>Default <application>WxWidgets</application> dependency
+ types</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Component</entry>
+
+ <entry>Dependency type</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>wx</literal></entry>
+
+ <entry><literal>lib</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>contrib</literal></entry>
+
+ <entry><literal>lib</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>python</literal></entry>
+
+ <entry><literal>run</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>mozilla</literal></entry>
+
+ <entry><literal>lib</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>svg</literal></entry>
+
+ <entry><literal>lib</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example id="wx-components-example">
+ <title>Selecting <application>WxWidgets</application>
+ components</title>
+
+ <para>The following fragment corresponds to a port which uses
+ <application>WxWidgets</application> version
+ <literal>2.4</literal> and its contributed libraries.</para>
+
+ <programlisting>USE_WX= 2.4
+WX_COMPS= wx contrib</programlisting>
+ </example>
+ </sect2>
+ <sect2 id="wx-unicode">
+ <title>Unicode</title>
+
+ <para>The <application>WxWidgets</application> library supports
+ Unicode since version <literal>2.5</literal>. In the ports tree both
+ versions are available and can be selected with the following
+ variables:</para>
+
+ <table id="wx-unicode-var-table" frame="none">
+ <title>Variables to select Unicode in
+ <application>WxWidgets</application>
+ versions</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+
+ <entry>Description</entry>
+
+ <entry>Designed for</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>WX_UNICODE</makevar></entry>
+
+ <entry>The port works <emphasis>only</emphasis> with the
+ Unicode version</entry>
+
+ <entry>the port</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WANT_UNICODE</makevar></entry>
+
+ <entry>The port works with both versions but prefers the
+ Unicode one</entry>
+
+ <entry>the port</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_UNICODE</makevar></entry>
+
+ <entry>The port will use the Unicode version</entry>
+
+ <entry>the user</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITHOUT_UNICODE</makevar></entry>
+
+ <entry>The port will use the normal version if
+ supported (when <makevar>WX_UNICODE</makevar> is not
+ defined)</entry>
+
+ <entry>the user</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <warning>
+ <para>Do not use <makevar>WX_UNICODE</makevar> for ports that can
+ use both Unicode and normal versions. If you want the port to use
+ Unicode by default define <makevar>WANT_UNICODE</makevar>
+ instead.</para>
+ </warning>
+ </sect2>
+
+ <sect2 id="wx-version-detection">
+ <title>Detecting installed versions</title>
+
+ <para>To detect an installed version you have to define
+ <makevar>WANT_WX</makevar>. If you do not set it to a specific
+ version then the components will have a version suffix. The
+ <makevar>HAVE_WX</makevar> variable will be filled after
+ detection.</para>
+
+ <example id="wx-ver-det-example">
+ <title>Detecting installed <application>WxWidgets</application>
+ versions and components</title>
+
+ <para>The following fragment can be used in a port that uses
+ <application>WxWidgets</application> if it is installed, or an
+ option is selected.</para>
+
+ <programlisting>WANT_WX= yes
+
+.include <bsd.port.pre.mk>
+
+.if defined(WITH_WX) || ${HAVE_WX:Mwx-2.4} != ""
+USE_WX= 2.4
+CONFIGURE_ARGS+=--enable-wx
+.endif</programlisting>
+
+ <para>The following fragment can be used in a port that enables
+ <application>WxPython</application> support if it is installed or
+ if an option is selected, in addition to
+ <application>WxWidgets</application>, both version
+ <literal>2.6</literal>.</para>
+
+ <programlisting>USE_WX= 2.6
+WX_COMPS= wx
+WANT_WX= 2.6
+
+.include <bsd.port.pre.mk>
+
+.if defined(WITH_WXPYTHON) || ${HAVE_WX:Mpython} != ""
+WX_COMPS+= python
+CONFIGURE_ARGS+=--enable-wxpython
+.endif</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="wx-defined-variables">
+ <title>Defined variables</title>
+
+ <para>The following variables are defined after defining one of the
+ variables from <xref linkend="wx-ver-sel-table">.</para>
+
+ <table frame="none">
+ <title>Variables defined for ports that use
+ <application>WxWidgets</application></title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>WX_CONFIG</makevar></entry>
+
+ <entry>The path to the <application>WxWidgets</application>
+ <literal>wx-config</literal> script (with different
+ name)</entry>
+ </row>
+ <row>
+ <entry><makevar>WXRC_CMD</makevar></entry>
+
+ <entry>The path to the <application>WxWidgets</application>
+ <literal>wxrc</literal> program (with differen name)</entry>
+ </row>
+ <row>
+ <entry><makevar>WX_VERSION</makevar></entry>
+
+ <entry>The <application>WxWidgets</application> version that
+ is going to be used (e.g., <literal>2.6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WX_UNICODE</makevar></entry>
+
+ <entry>If not defined but Unicode is going to be used then it
+ will be defined</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+ <sect2 id="wx-premk">
+ <title>Processing in <filename>bsd.port.pre.mk</filename></title>
+
+ <para>If you need to use the variables for running commands right
+ after including <filename>bsd.port.pre.mk</filename> you need to
+ define <makevar>WX_PREMK</makevar>.</para>
+
+ <important>
+ <para>If you define <makevar>WX_PREMK</makevar>, then the version,
+ dependencies, components and defined variables will not change if
+ you modify the <application>Lua</application> port variables
+ <emphasis>after</emphasis> including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </important>
+
+ <example id="wx-premk-example">
+ <title>Using <application>WxWidgets</application> variables in
+ commands</title>
+
+ <para>The following fragment illustrates the use of
+ <makevar>WX_PREMK</makevar> by running the
+ <application>Lua</application> interpreter to obtain the full
+ version string, assign it to a variable and pass it to the
+ program.</para>
+
+ <programlisting>USE_WX= 2.4
+WX_PREMK= yes
+
+.include <bsd.port.pre.mk>
+
+.if exists(${WX_CONFIG})
+VER_STR!= ${WX_CONFIG} --release
+
+PLIST_SUB+= VERSION="${VER_STR}"
+.endif</programlisting>
+ </example>
+
+ <note>
+ <para>The <application>WxWidgets</application> variables can be
+ safely used in commands when they are inside targets without the
+ need of <makevar>WX_PREMK</makevar>.</para>
+ </note>
+ </sect2>
</sect1>
<sect1 id="using-lua">
--- patch_wx.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1163455839.24155>