CMake Overview

Table of Contents

• Using the CMake GUI
• Using the CMake Command Line
  • Command Line Examples
• Build options
• Recommendations
• Using CMake with your applications
  • Using find_package
  • Using a sub directory
  • Using XRC

CMake allows building wxWidgets on various platforms with your preferred build system.

Most linux distributions contain CMake as a package on Windows and macOS you can download an installer at the CMake Page.

Using the CMake GUI

1. Start the CMake GUI
2. Specify the wxWidgets root as your source folder
3. Specify a path where the build files should be created. It's recommended to use a path outside the wxWidgets root folder.
4. Press the Configure button and you will be asked which IDE or build system you wish to use
5. Optionally: Customize any of the options
6. Press the Generate button
7. Open the wxWidgets project with your preferred IDE

Using the CMake Command Line

1. Create a folder where the build/project files should be created
2. Change into the created folder
3. Run cmake -G "Unix Makefiles" path_to_wxWidgets_root
4. After that you can run cmake --build . to start the build process or directly use your chosen build system.

Run cmake --help to see a list of available generators on your platform. These can than be specified using the -G command line option. On Windows it is recommended to use Visual Studio and on macOS Xcode is recommended. Various build options can be specified using -D see available options.

Command Line Examples

Building with tests using Ninja:

cmake -G "Ninja" ~/Downloads/wxWidgets_3.1 -DwxBUILD_TESTS=ALL
cmake --build .

Building the minimal sample:

cmake ~/Downloads/wxWidgets_3.1 -DwxBUILD_SAMPLES=SOME
cmake --build . --target minimal

Installing static libraries to some path:

cmake ~/Downloads/wxWidgets_3.1 \
  -DCMAKE_INSTALL_PREFIX=~/wx_install \
  -DwxBUILD_SHARED=OFF
cmake --build . --target install

Build options

The following list of build options can either be configured in the CMake UI or specified via the -D command line option when running the cmake command.

Option Name	Type	Default	Description
wxBUILD_SHARED	BOOL	ON	Build shared or static libraries
wxBUILD_TESTS	STRING	OFF	CONSOLE_ONLY, ALL or OFF
wxBUILD_SAMPLES	STRING	OFF	SOME, ALL or OFF
wxBUILD_DEMOS	BOOL	OFF	Build demo applications
wxUSE_GUI	BOOL	ON	Build the UI libraries
wxBUILD_COMPATIBILITY	STRING	3.2	Enable API compatibility with 3.0, 3.2 or neither ("NONE")
wxBUILD_PRECOMP	BOOL	ON	Use precompiled headers
wxBUILD_MONOLITHIC	BOOL	OFF	Build a single library

Note that on macOS, the option CMAKE_OSX_ARCHITECTURES is used to specify which architecture(s) to build. For example, the following will build a "universal binary 2" (i.e., ARM64 and Intel x86_64) library.

cmake ~/Downloads/wxWidgets_3.1 \
  -DCMAKE_INSTALL_PREFIX=~/wx_install \
  -DwxBUILD_SHARED=OFF
  -D"CMAKE_OSX_ARCHITECTURES:STRING=arm64;x86_64"
cmake --build . --target install

A complete list of options and advanced options can be found when using the CMake GUI.

Recommendations

While CMake in wxWidgets aims to support most generators available in CMake, the following generators are recommended:

• Windows: Visual Studio (any supported version)
• macOS: Xcode
• Linux: Ninja or Makefiles

CMake 3.10 or newer is recommended. The minimum tested version is 3.5.

Using CMake with your applications

If you are using CMake with your own application, there are various ways to use wxWidgets:

• Using an installed, binary or compiled version of wxWidgets using find_package()
• wxWidgets as a sub directory.
• CMake's ExternalProject module.

Using find_package

You can use find_package(wxWidgets) to use a compiled version of wxWidgets. Have a look at the CMake Documentation for detailed instructions. wxWidgets also provides an example CMake file in the minimal sample folder.

WARNING: Please note that CMake findwxWidgets module unfortunately doesn't detect wxWidgets 3.2.0 in versions of CMake older than 3.24. You may copy the latest version of FindwxWidgets.cmake from CMake sources to your system to fix this or, if you build wxWidgets itself using CMake, use CONFIG mode of find_package() which works even with older CMake versions.

Your CMakeLists.txt would look like this:

...
 
find_package(wxWidgets REQUIRED COMPONENTS net core base)
if(wxWidgets_USE_FILE) # not defined in CONFIG mode
    include(${wxWidgets_USE_FILE})
endif()
add_executable(myapp myapp.cpp)
target_link_libraries(myapp ${wxWidgets_LIBRARIES})

Using a sub directory

You can use wxWidgets as a subdirectory in your application's build tree e.g. as a git submodule. This way the wxWidgets libraries will be part of your applications build process.

Your CMakeLists.txt would look like this:

...
add_subdirectory(libs/wxWidgets)
add_executable(myapp myapp.cpp)
target_link_libraries(myapp wx::net wx::core wx::base)

Note that you can predefine the build options before using add_subdirectory() by either defining them on command line with e.g. -DwxBUILD_SHARED=OFF, or by adding

set(wxBUILD_SHARED OFF)

to your CMakeLists.txt if you want to always use static wxWidgets libraries.

Using XRC

To embed XRC resources into your application, you need to define a custom command to generate a source file using wxrc. When using an installed version of wxWidgets you can just use wxrc directly, but when using wxWidgets from a subdirectory you need to ensure that it is built first and use the correct path to it, e.g.:

# One or more XRC files containing your resources.
set(xrc_files ${CMAKE_CURRENT_SOURCE_DIR}/resource.xrc)
 
# Generate this file somewhere under the build directory.
set(resource_cpp ${CMAKE_CURRENT_BINARY_DIR}/resource.cpp)
 
# Not needed with the installed version, just use "wxrc".
set(wxrc $<TARGET_FILE:wxrc>)
 
add_custom_command(
    OUTPUT ${resource_cpp}
    COMMAND ${wxrc} -c -o ${resource_cpp} ${xrc_files}
    DEPENDS ${xrc_files}
    DEPENDS wxrc                        # Not needed with the installed version.
    COMMENT "Compiling XRC resources"
)
 
target_sources(myapp PRIVATE ${resource_cpp})