6.18. Using wxWidgets
Prev | Chapter 6. Special Considerations | Next

## 6.18. Using wxWidgets

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

### 6.18.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.18.2. Version Selection

To make your 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.25. Variables to Select wxWidgets Versions

Variable | Description | Default value
--- | --- | ---
`USE_WX` | List of versions the port can use | All available versions
`USE_WX_NOT` | List of versions the port can not use | None

The following is a list of available wxWidgets versions and the corresponding ports in the tree:

Table 6.26. Available wxWidgets Versions

Version | Port
--- | ---
`2.4` | `x11-toolkits/wxgtk24`
`2.6` | `x11-toolkits/wxgtk26`
`2.8` | `x11-toolkits/wxgtk28`

### 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.18.4, “Unicode”).

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

Table 6.27. wxWidgets Version Specifications

Description | Example
--- | ---
Single version | `2.4`
Ascending range | `2.4+`
Descending range | `2.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.28. Variables to Select Preferred wxWidgets Versions

Name | Designed for
--- | ---
`WANT_WX_VER` | the port
`WITH_WX_VER` | the user

### 6.18.3. Component Selection

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

Table 6.29. Available wxWidgets Components

Name | Description | Version restriction
--- | --- | ---
`wx` | main library | none
`contrib` | contributed libraries | `none`
`python` | wxPython (Python bindings) | `2.4-2.6`
`mozilla` | wxMozilla | `2.4`
`svg` | wxSVG | `2.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.31, “Default wxWidgets Dependency Types”). The following types are available:

Table 6.30. Available wxWidgets Dependency Types

Name | Description
--- | ---
`build` | Component is required for building, equivalent to `BUILD_DEPENDS`
`run` | Component is required for running, equivalent to `RUN_DEPENDS`
`lib` | Component is required for building and running, equivalent to `LIB_DEPENDS`

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

Table 6.31. Default wxWidgets Dependency Types

Component | Dependency type
--- | ---
`wx` | `lib`
`contrib` | `lib`
`python` | `run`
`mozilla` | `lib`
`svg` | `lib`

Example 6.8. Selecting wxWidgets Components

The following fragment corresponds to a port which uses wxWidgets version `2.4` and its contributed libraries.

USE_WX= 2.4 WX_COMPS= wx contrib

### 6.18.4. Unicode

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

Table 6.32. Variables to Select Unicode in wxWidgets Versions

Variable | Description | Designed for
--- | --- | ---
`WX_UNICODE` | The port works only with the Unicode version | the port
`WANT_UNICODE` | The port works with both versions but prefers the Unicode one | the port
`WITH_UNICODE` | The port will use the Unicode version | the user
`WITHOUT_UNICODE` | The 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 you want the port to use Unicode by default define `WANT_UNICODE` instead.

### 6.18.5. Detecting Installed Versions

To detect an installed version you have to define `WANT_WX`. If you do not set it to a specific version then the components will have a version suffix. The `HAVE_WX` variable will be filled after detection.

Example 6.9. Detecting Installed wxWidgets Versions and Components

The following 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

The following 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.18.6. Defined Variables

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

Table 6.33. Variables Defined for Ports That Use wxWidgets

Name | Description
--- | ---
`WX_CONFIG` | The path to the wxWidgets `wx-config` script (with different name)
`WXRC_CMD` | The path to the wxWidgets `wxrc` program (with different name)
`WX_VERSION` | The wxWidgets version that is going to be used (e.g., `2.6`)
`WX_UNICODE` | If not defined but Unicode is going to be used then it will be defined

### 6.18.7. Processing in `bsd.port.pre.mk`

If you need to use the variables for running commands right after including `bsd.port.pre.mk` you need to define `WX_PREMK`.

### Important:

If you define `WX_PREMK`, then the version, dependencies, components and defined variables will not change if you modify the wxWidgets port variables after including `bsd.port.pre.mk`.

Example 6.10. Using wxWidgets Variables in Commands

The following 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.18.8. Additional `configure` Arguments

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

Table 6.34. Legal Values for `WX_CONF_ARGS`

Possible value | Resulting argument
--- | ---
`absolute` | `--with-wx-config=${WX_CONFIG}`
`relative` | `--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}`

Prev | Up | Next
6.17. Using SDL | Home | 6.19. Using Lua

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 <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.