6.20. Using wxWidgets

This section describes the status of the wxWidgets libraries in the ports tree and its integration with the ports system.

6.20.1. Introduction

There are many versions of the wxWidgets 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.

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 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 be patched.

6.20.2. Version Selection

To make the port use a specific version of wxWidgets there are two variables available for defining (if only one is defined the other will be set to a default value):

Table 6.23. Variables to Select wxWidgets Versions
VariableDescriptionDefault value
USE_WXList of versions the port can useAll available versions
USE_WX_NOTList of versions the port cannot useNone

The available wxWidgets versions and the corresponding ports in the tree are:

Table 6.24. Available wxWidgets Versions

Note:

The versions starting from 2.5 also come in Unicode version and are installed by a slave port named like the normal one plus a -unicode suffix, but this can be handled with variables (see Section 6.20.4, “Unicode”).

The variables in Table 6.23, “Variables to Select wxWidgets Versions” can be set to one or more of these combinations separated by spaces:

Table 6.25. wxWidgets Version Specifications
DescriptionExample
Single version2.4
Ascending range2.4+
Descending range2.6-
Full range (must be ascending)2.4-2.6

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.

Table 6.26. Variables to Select Preferred wxWidgets Versions
NameDesigned for
WANT_WX_VERthe port
WITH_WX_VERthe user

6.20.3. Component Selection

There are other applications that, while not being wxWidgets libraries, are related to them. These applications can be specified in WX_COMPS. These components are available:

Table 6.27. Available wxWidgets Components
NameDescriptionVersion restriction
wxmain librarynone
contribcontributed librariesnone
pythonwxPython (Python bindings)2.4-2.6
mozillawxMozilla2.4
svgwxSVG2.6

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 Table 6.29, “Default wxWidgets Dependency Types”). These types are available:

Table 6.28. Available wxWidgets Dependency Types
NameDescription
buildComponent is required for building, equivalent to BUILD_DEPENDS
runComponent is required for running, equivalent to RUN_DEPENDS
libComponent is required for building and running, equivalent to LIB_DEPENDS

The default values for the components are detailed in this table:

Table 6.29. Default wxWidgets Dependency Types
ComponentDependency type
wxlib
contriblib
pythonrun
mozillalib
svglib

Example 6.11. Selecting wxWidgets Components

This fragment corresponds to a port which uses wxWidgets version 2.4 and its contributed libraries.

USE_WX=		2.4
WX_COMPS=	wx contrib

6.20.4. Unicode

The wxWidgets library supports Unicode since version 2.5. In the ports tree both versions are available and can be selected with these variables:

Table 6.30. Variables to Select Unicode in wxWidgets Versions
VariableDescriptionDesigned for
WX_UNICODEThe port works only with the Unicode versionthe port
WANT_UNICODEThe port works with both versions but prefers the Unicode onethe port
WITH_UNICODEThe port will use the Unicode versionthe user
WITHOUT_UNICODEThe port will use the normal version if supported (when WX_UNICODE is not defined)the user

Warning:

Do not use WX_UNICODE for ports that can use both Unicode and normal versions. If the port needs to use Unicode by default, define WANT_UNICODE instead.

6.20.5. Detecting Installed Versions

To detect an installed version, define WANT_WX. If it is not set to a specific version then the components will have a version suffix. HAVE_WX will be filled after detection.

Example 6.12. Detecting Installed wxWidgets Versions and Components

This fragment can be used in a port that uses wxWidgets if it is installed, or an option is selected.

WANT_WX=	yes

.include <bsd.port.pre.mk>

.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4)
USE_WX=			2.4
CONFIGURE_ARGS+=	--enable-wx
.endif

This fragment can be used in a port that enables wxPython support if it is installed or if an option is selected, in addition to wxWidgets, both version 2.6.

USE_WX=		2.6
WX_COMPS=	wx
WANT_WX=	2.6

.include <bsd.port.pre.mk>

.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython)
WX_COMPS+=		python
CONFIGURE_ARGS+=	--enable-wxpython
.endif

6.20.6. Defined Variables

These variables are available in the port (after defining one from Table 6.23, “Variables to Select wxWidgets Versions”).

Table 6.31. Variables Defined for Ports That Use wxWidgets
NameDescription
WX_CONFIGThe path to the wxWidgets wx-config script (with different name)
WXRC_CMDThe path to the wxWidgets wxrc program (with different name)
WX_VERSIONThe wxWidgets version that is going to be used (for example, 2.6)
WX_UNICODEIf not defined but Unicode is going to be used then it will be defined

6.20.7. Processing in bsd.port.pre.mk

Define WX_PREMK to be able to use the variables right after including bsd.port.pre.mk.

Important:

When defining WX_PREMK, then the version, dependencies, components and defined variables will not change if modifying the wxWidgets port variables after including bsd.port.pre.mk.

Example 6.13. Using wxWidgets Variables in Commands

This fragment illustrates the use of WX_PREMK by running the wx-config script to obtain the full version string, assign it to a variable and pass it to the program.

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

Note:

The wxWidgets variables can be safely used in commands when they are inside targets without the need of WX_PREMK.

6.20.8. Additional configure Arguments

Some GNU configure scripts cannot find wxWidgets with just the WX_CONFIG environment variable set, requiring additional arguments. WX_CONF_ARGS can be used for provide them.

Table 6.32. Legal Values for WX_CONF_ARGS
Possible valueResulting argument
absolute--with-wx-config=${WX_CONFIG}
relative--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <[email protected]>.
Send questions about this document to <[email protected]>.