Compiling and getting started

This is a guide to help you get started quickly and easily on Linux with wxWidgets built from source.

Before starting

Install all necessary build tools, including g++ and autotools. One easy way to do this on many distros is to install the 'build-essential' package.

The standard wx build on Linux is wxGTK. The gtk libs should already be installed, but you will also need gtk development package if your distro uses them. For debian and derivatives (e.g. ubuntu, mint) this will be libgtk2.0-dev for gtk2 (which in 2014 is the 'normal' version), or libgtk-3-dev for gtk3, On fedora and openSUSE the equivalents are gtk2-devel and gtk3-devel.

wxWidgets

Download the wxWidgets source archive, the tar.bz2 one as this has the correct line-endings, from http://www.wxwidgets.org/downloads/ and extract it. If you intend to use it in place (not install it in system dirs) choose a place where it can stay forever because you won't be able to move it without breaking the build.

Then the following steps are done in a terminal:

cd /path/to/wxWidgets-3.0.x # adapt path as needed
mkdir gtk-build # or any other name you fancy
cd gtk-build

Why create a new folder to build in? Partly because it separates the .o files from the source, but mostly because it makes it easy to have multiple different wxWidgets builds, e.g. a debug and a release one, a static and a shared one... If you configure with --prefix=<somewhere> (see below) each build can be installed to a different directory; this prevents different builds from clashing.

Then call ../configure. Note the '..'; the configure script is in the parent dir. For wx2.8 you might do:

../configure --enable-unicode --enable-debug

For wx3 unicode is the default, and you only need --enable-debug if you want to build the wx samples with debug symbols; so just ./configure is sufficient for many situations.

The options you pass to configure at this point will determine what build you get.

--enable-unicode	makes a Unicode build
--with-opengl	enables OpenGL support
--disable-shared	builds static libs instead of shared ones
--prefix=[...]	makes wxWidgets install to a different location from the default /usr/local

One option I find especially useful is --prefix=$(pwd). This says to install into the current dir, which means 1) you know exactly where it is, 2) you don't need superuser permissions, and 3) you don't need to 'make install'.

For a list of all possible options, do ../configure --help. However most of these are very rarely needed.

When configure stops, read the output. It might say it can't find a dependency; if so, install the appropriate development packages and run configure again. When it completes without errors, you are ready to build.

make

or

make -j

Use the '-j' option with care because it can drive your system out out of memory. Best match the number of jobs to the number of CPU cores you have, e.g. '-j4' for a 4core CPU.

When the build is done, and if no error occured, you must now install it (unless you did --prefix=$(pwd) as above). Become superuser if necessary, and do:

make install

By default wxWidgets will be installed to /usr/local/

On some systems it is then necesary to run ldconfig.

Test the installation

For a standard install, open a terminal and type

wx-config --version

It should be the version you just built. If it isn't, or for other --prefix installs, you can either do:

/full/path/to/that/wx-config --version

or prepend that dir to your PATH e.g.

PATH=/full/path/to/that/wx-config:$PATH

Then, to test more in depth, run some of the samples. Their source code lives in the samples subdir of the source dir; the makefiles are in gtk-build/samples. So, to build 'minimal':

cd gtk-build/samples/minimal
make
./minimal

'minimal' and 'widgets' are respectively the simplest and the most complete samples.

Building apps with wxWidgets

The tool wx-config allows you to quickly build wxWidgets apps:

g++ widgetTest.cpp `wx-config --cxxflags --libs` -o widgetTest

will compile widgetTest.cpp and create a binary called 'widgetTest'.

wx-config --cxxflags returns flags needed for compilation; wx-config --libs returns those for linking. This little example has a single file so both are used at the same time but in a bigger project compiling and linking will most likely be two different steps (and probably using a makefile).

For more information, see article Wx-Config. Note especially the Important note for wx3.0 and later section if you use the 'extra' wx libs e.g. 'aui'.

Running wxWidgets projects

If when running a wxWidgets app you get an error like:

./a.out: error while loading shared libraries: libwx_baseu-3.0.so.0: cannot open shared object file: No such file or directory

this means your system does not search for libs in /usr/local/libs (or wherever you installed wxWidgets) by default. To solve this, any of the following should work :

• Write export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib on the terminal before opening the executable (from the same terminal). To save having to do this each time, add that line to your ~/.bashrc or similar.
• Give a --rpath /usr/local/lib/ flag to the linker while building (tip: since you generally don't invoke the linker directly, but rather perform linking through GCC, use GCC's syntax to pass along flags to the linker : -Wl,--rpath,/usr/local/lib/)
• Become root and execute /sbin/ldconfig /usr/local/lib. This will configure dynamic linker runtime bindings, adding all the libraries in /usr/local/lib, so it's not really a very good idea!