From alepulver@FreeBSD.org  Mon Nov 13 22:11:32 2006
Return-Path: <alepulver@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id E7A6E16A4D8
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 13 Nov 2006 22:11:31 +0000 (UTC)
	(envelope-from alepulver@FreeBSD.org)
Received: from relay01.pair.com (relay01.pair.com [209.68.5.15])
	by mx1.FreeBSD.org (Postfix) with SMTP id 850A943DA1
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 13 Nov 2006 22:11:03 +0000 (GMT)
	(envelope-from alepulver@FreeBSD.org)
Received: (qmail 66590 invoked from network); 13 Nov 2006 22:10:42 -0000
Received: from unknown (HELO phobos.mars.bsd) (unknown)
  by unknown with SMTP; 13 Nov 2006 22:10:42 -0000
Message-Id: <1163455839.24155@phobos.mars.bsd>
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: [PATCH] PH: rewrite WxWidgets entry
X-Send-Pr-Version: gtk-send-pr 0.4.7 
X-GNATS-Notify:

>Number:         105494
>Category:       docs
>Synopsis:       [PATCH] PH: rewrite WxWidgets entry
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    alepulver
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Mon Nov 13 22:20:06 GMT 2006
>Closed-Date:    Sun Feb 18 00:14:46 GMT 2007
>Last-Modified:  Sun Feb 18 00:14:46 GMT 2007
>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 &lt;bsd.port.pre.mk&gt;
+
+.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 &lt;bsd.port.pre.mk&gt;
+
+.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 &lt;bsd.port.pre.mk&gt;
+
+.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:

From: Pav Lucistnik <pav@FreeBSD.org>
To: Alejandro Pulver <alepulver@FreeBSD.org>
Cc: FreeBSD gnats submit <FreeBSD-gnats-submit@FreeBSD.org>
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Mon, 13 Nov 2006 23:52:28 +0100

 > >Number:         105494
 > >Synopsis:       [PATCH] PH: rewrite WxWidgets entry
 
 Some comments on your patch:
 
 - please keep using wxWidgets, with small first w. That's how the
   project is called, check http://www.wxwidgets.org/ for proof
 
 - please be consistent with double space after full stop
 
 - 
 
 > +	  be modified to found the expected version. Fortunately most of the
 
 - to find the expected version
 
 > +	  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
 
 - this overly long sentence is confusing! It could use a split into four
   standalone, clear ones. What about
 
 Fortunately, most of the applications call the wx-config script to
 determine the necessary compiler and linker flags. The script is named
 differently for every available version. Majority of applications
 respect an environment variable, or accept a configure argument, to
 specify which wx-config script to call. Otherwise they have to patched.
 
 > +	<para>The following is a list of available
 > +	  <application>WxWidgets</application> versions and the corresponding
 > +	  port in the tree:</para>
 
 - corresponding ports
 
 > +	  <para>The <literal>2.6</literal> version also comes in Unicode and
 
 - also comes in Unicode - version? variant? modification?
 
 > +		<entry><application>WxPython</application>
 
 - wxPython
 
 > +		<entry><application>WxMozilla</application></entry>
 
 - wxMozilla
 
 > +		<entry><application>WxSVG</application></entry>
 
 - wxSVG
 
 > +	<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
 
 - this is confusing, please rephrase.
 
 The dependency type can be selected for each component by adding a
 suffix separated by a semicolon.
 
 > +	<para>The following variables are defined after defining one of the
 > +	  variables from <xref linkend="wx-ver-sel-table">.</para>
 
 - overuse of defined. What about
 
 The following variables are available in the port:
 
 > +		  <literal>wxrc</literal> program (with differen name)</entry>
 
 - with different name
 
 > +	    you modify the <application>Lua</application> port variables
 
 - should this really read Lua?
 
 > +	    <application>Lua</application> interpreter to obtain the full
 
 - again, should this read Lua?
 
 Awaiting corrected patch.
 
 -- 
 Pav Lucistnik <pav@oook.cz>
               <pav@FreeBSD.org>
 
 Some programmers are able to write FORTRAN in any language.

From: Alejandro Pulver <alepulver@FreeBSD.org>
To: pav@FreeBSD.org
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Tue, 14 Nov 2006 15:00:56 -0300

 On Mon, 13 Nov 2006 23:52:28 +0100
 Pav Lucistnik <pav@FreeBSD.org> wrote:
 
 > > >Number:         105494
 > > >Synopsis:       [PATCH] PH: rewrite WxWidgets entry
 > 
 > Some comments on your patch:
 > 
 [...]
 > Awaiting corrected patch.
 > 
 
 Hello.
 
 I have incorporated your corrections in the following patch, if it is
 fine then I will send another one for Lua.
 
 Index: book.sgml
 ===================================================================
 RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.767
 diff -u -r1.767 book.sgml
 --- book.sgml	13 Nov 2006 22:31:33 -0000	1.767
 +++ book.sgml	14 Nov 2006 17:59:46 -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 find the expected version. Fortunately, most of the
 +	  applications call the <command>wx-config</command> script to
 +	  determine the necessary compiler and linker flags. The script is
 +	  named differently for every available version. Majority of
 +	  applications respect an environment variable, or accept a configure
 +	  argument, to specify which <command>wx-config</command> script to
 +	  call. Otherwise they have to patched.</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
 +	  ports 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 can be selected for each component by adding
 +	  a suffix separated by a semicolon. If not present then a default
 +	  type will be used (see <xref linkend="wx-def-dep-types">). The
 +	  following types are available:</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 id="wx-def-dep-types" 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 &lt;bsd.port.pre.mk&gt;
 +
 +.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 &lt;bsd.port.pre.mk&gt;
 +
 +.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 available in the port (after
 +	  defining one 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>
 +		  <command>wx-config</command> script (with different
 +		  name)</entry>
 +	      </row>
 +	      <row>
 +		<entry><makevar>WXRC_CMD</makevar></entry>
 +
 +		<entry>The path to the <application>wxWidgets</application>
 +		  <command>wxrc</command> program (with different
 +		  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>wxWidgets</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
 +	    <command>wx-config</command> script 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 &lt;bsd.port.pre.mk&gt;
 +
 +.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">
 
 Best Regards,
 Ale

From: Pav Lucistnik <pav@FreeBSD.org>
To: Alejandro Pulver <alepulver@FreeBSD.org>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Tue, 14 Nov 2006 20:10:47 +0100

 > I have incorporated your corrections in the following patch, 
 
 > +	  be modified to find the expected version. Fortunately, most of the
 
 Still missing double space after full stop.
 
 > +         call. Otherwise they have to patched.</para>
 
 "they have to be patched". Sorry, I wrote it badly in my previous mail.
 
 > +	  <para>The <literal>2.6</literal> version also comes in Unicode and
 > +	    is installed by the slave port <filename
 
 Still unclear what Unicode is here. Can you rephrase it a little?
 
 > +	  a suffix separated by a semicolon. If not present then a default
 
 Double space missing here, and several places elsewhere. Please double
 check!
 
 Otherwise it looks promising so far.
 
 -- 
 Pav Lucistnik <pav@oook.cz>
               <pav@FreeBSD.org>
 
 > Why do we need a film of "Lord of the Rings" when we have the book?
 Because watching a cg enhanced Legolas fire a flaming arrow
 into the heart of a warg is cool?
     - asdf@asdf.com in rec.games.roguelike.angband

From: Alejandro Pulver <alepulver@FreeBSD.org>
To: pav@FreeBSD.org
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Tue, 14 Nov 2006 21:06:20 -0300

 O.K., here is a new one.
 
 Index: book.sgml
 ===================================================================
 RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.767
 diff -u -r1.767 book.sgml
 --- book.sgml	13 Nov 2006 22:31:33 -0000	1.767
 +++ book.sgml	15 Nov 2006 00:05:12 -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 find the expected version.  Fortunately, most of the
 +	  applications call the <command>wx-config</command> script to
 +	  determine the necessary compiler and linker flags.  The script is
 +	  named differently for every available version.  Majority of
 +	  applications respect an environment variable, or accept a configure
 +	  argument, to specify which <command>wx-config</command> script to
 +	  call.  Otherwise they have to be patched.</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
 +	  ports 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
 +	    version 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 can be selected for each component by adding
 +	  a suffix separated by a semicolon.  If not present then a default
 +	  type will be used (see <xref linkend="wx-def-dep-types">).  The
 +	  following types are available:</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 id="wx-def-dep-types" 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 &lt;bsd.port.pre.mk&gt;
 +
 +.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 &lt;bsd.port.pre.mk&gt;
 +
 +.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 available in the port (after
 +	  defining one 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>
 +		  <command>wx-config</command> script (with different
 +		  name)</entry>
 +	      </row>
 +	      <row>
 +		<entry><makevar>WXRC_CMD</makevar></entry>
 +
 +		<entry>The path to the <application>wxWidgets</application>
 +		  <command>wxrc</command> program (with different
 +		  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>wxWidgets</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
 +	    <command>wx-config</command> script 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 &lt;bsd.port.pre.mk&gt;
 +
 +.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">

From: Pav Lucistnik <pav@FreeBSD.org>
To: Alejandro Pulver <alepulver@FreeBSD.org>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Wed, 15 Nov 2006 10:20:24 +0100

 > O.K., here is a new one.
 
 Looks good, please test build and commit.
 
 -- 
 Pav Lucistnik <pav@oook.cz>
               <pav@FreeBSD.org>
 
 What is the airspeed velocity of an unladen swallow?

From: Alejandro Pulver <alepulver@FreeBSD.org>
To: pav@FreeBSD.org
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/105494: [PATCH] PH: rewrite WxWidgets entry
Date: Thu, 16 Nov 2006 20:46:44 -0300

 --Sig_LljVVEGmSy1U3BBI/ATjcuL
 Content-Type: text/plain; charset=US-ASCII
 Content-Transfer-Encoding: quoted-printable
 
 On Wed, 15 Nov 2006 10:20:24 +0100
 Pav Lucistnik <pav@FreeBSD.org> wrote:
 
 > > O.K., here is a new one.
 >=20
 > Looks good, please test build and commit.
 >=20
 
 Done.
 
 Best Regards,
 Ale
 
 --Sig_LljVVEGmSy1U3BBI/ATjcuL
 Content-Type: application/pgp-signature; name=signature.asc
 Content-Disposition: attachment; filename=signature.asc
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.5 (FreeBSD)
 
 iD8DBQFFXPhqiV05EpRcP2ERAnrKAKC4f2oaLwBMk1PB0hXnrYgft/UoBACfZJSq
 HCUoJP0xwVyklbhKAGIMqXE=
 =G64T
 -----END PGP SIGNATURE-----
 
 --Sig_LljVVEGmSy1U3BBI/ATjcuL--
State-Changed-From-To: open->closed 
State-Changed-By: gabor 
State-Changed-When: Sun Feb 18 00:13:57 UTC 2007 
State-Changed-Why:  
Already committed by alepulver. 


Responsible-Changed-From-To: freebsd-doc->alepulver 
Responsible-Changed-By: gabor 
Responsible-Changed-When: Sun Feb 18 00:13:57 UTC 2007 
Responsible-Changed-Why:  
Already committed by alepulver. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=105494 
>Unformatted:
