Difference between revisions of "Compiling and getting started"
m (Correct reference to monolithic being default) |
m (Correct premature references to wx3.0.5) |
||
| Line 8: | Line 8: | ||
:<syntaxhighlight lang="DOS"> | :<syntaxhighlight lang="DOS"> | ||
Windows A) Linux Default B) Linux Alternative | Windows A) Linux Default B) Linux Alternative | ||
| − | wxWidgets3.0. | + | wxWidgets3.0.4 wxWidgets3.0.4 wxWidgets3.0.4 |
[...] [...] [...] | [...] [...] [...] | ||
lib buildgtk buildgtk // our build folder | lib buildgtk buildgtk // our build folder | ||
Revision as of 13:29, 3 February 2020
Back to Install
This is a guide to help you get started quickly and easily on Linux with wxWidgets built from source.
Before starting
wxWidgets is a cross-platform systen and it does not hide the platform from you. When compiling wxWidgets from source in different systems you will note that the resulting installations will (slightly) differ between the operating systems. This is particulary evident in the way the compiled libraries are handled between Linux derived platforms and the Windows platform. Here are the different structures side-by-side. Note that the same sources are used. Here is the library structure as example (it does only show relevant folders)
Windows A) Linux Default B) Linux Alternative wxWidgets3.0.4 wxWidgets3.0.4 wxWidgets3.0.4 [...] [...] [...] lib buildgtk buildgtk // our build folder gcc_dll lib lib mswu <empty> gtk2u_so // shared library, release mswud [...] bin gcc_lib include vc_dll lib vc_lib share [...] gtk2ud_so // debug gtk2u_lib // static gtk3u_so // GTK3 version [...]- This shows the different structures between OS. A) and B) mean two possible ways to set up the compilation in Linux.
For the case A) the compiled libraries are stored in a system folder (typically /usr/local/lib), thus default lib folder will remain empty. In case B) we see that the folder structure for each library also is totally different. The 'bin' sub-folder contain as sym-link to a file in the 'lib' folder structure that allows the 'wx-config' feature to work.
Case A) is the standard approach in Linux and is much quicker. You use it for shared libraries, which is what most programs in Linux would use. You should use this if you build wxWidgets to compile some other third party software, because it would the closest to the standard setup that software developer would expect. Its also the best setup to use when you are planning to develop with wxWidgets using the command line interface (CLI).
Case B) installs the libraries and the other required files into a folder of your selection. It mimics the way the windows structure is set up. It might be more familiar to set up in your favourite cross-platform IDE. Its the best setup if you build your lib for only a very specific purpose or very often change your configuration. It gives you the full control on what is on the system but also the full worries about paths etc. Its also your only option if you do not have admin rights on you computer.
Its a disadvantage for working on the command line, because you need to make sure all the 'bin' folders are in to your $PATH variable. Otherwise 'wx-condig --list' would not run or only find one of your installations.
Notes
- The example codes below work on Ubuntu Linux and should work the same way with most Debian based distros. For other distros there might be slight deviations (be invited to add the wiki at the appropriate sections)
- There is an installation help file in every source archive under
doc/gtk/install.mdwhich also contains some additional information.
- Hint: If you are new to programming on the Linux platforms its a good idea to come back after compilation and continue to learn about the process until you understand the concepts behind each step of this procedure.
Prerequisites
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, e.g. for Ubuntu
sudo apt install build-essential
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. So you choose from
sudo apt install libgtk2.0-dev sudo apt install libgtk-3-dev
Getting the source
Download the wxWidgets source archive, the tar.bz2 one as this has the correct line-endings. The sources are OS independent, so there is only one source archive.
- Download from https://www.wxwidgets.org/downloads/
- Extract it. Here it depends if you want to do option A) or B) (see above)
- for an install in system dirs it does not matter where you put it. You could extract it to ~/temp and delete it after compilation.
- If you intend to use it in place extract it to the final place in your system, because you won't be able to move it without breaking the build. For the example we assume you put it in your home folder in
/home/$USER/wx. Remember to adapt the path accordingly.
Building the library
TL;DR: if you are in a hurry and know the details here is the default for case A) (see above)
cd ~/wx/wxWidgets-3.1.3
mkdir gtk-build # the name is not really relevant
cd gtk-build
../configure # builds unicode, shared lib
make -j3 # use 3 cores. Set to the number of cores your have. 'make' uses 1 core
sudo make install # some platforms require to use 'su' instead of 'sudo'
sudo ldconfig # not required in each system
Long Version: The following steps are done in a terminal in the root of wxWidgets. For the example we also assume the version 3.1.3
First create a build folder. This will not contain the final libraries, just all intermediate files. It also keeps the root level clean of temporary files. We need to put it into the wxWidgets directory, because it needs to access files in its root level. In this folder we will configure our builds and keep all temporary object files.
cd ~/wx/wxWidgets-3.1.3
mkdir gtk-build # the name is not really relevant, use what you like
cd gtk-build
Some people use several build folders, one for each configuration. So you could put a script file with each config in each and re-compile the library again when required. Then you should use a naming scheme telling which version is in which folder, e.g. gfk-Build_3d for GFK-3.0, debug. Since several folders eat up space, we are going to use only one and clean it up between our different builds with 'make clean'.
Now we select which version of the library we want to build
Then call ../configure. Note the '..'; the configure script is in the parent dir. Here are a few examples. Do not type the comments including and after "//"
../configure // create a shared lib (*.so) with standard settings
../configure --enable-debug // create a shared lib (*.so) with standard settings
../configure --with-gtk=3 // standard but with GTK3
../configure --disable-shared // make static libs (*.a)
../configure --with-opengl --with-gtk=3 // GTK3 defaults + allow to use OpenGL
../configure --enable-unicode --enable-debug // for 2.8 or earlier
Since wxWidgets-3.0 some options are set as default, so you do not need to specify those options (but it does not hurt to specify them either). So you only need very few option e.g. --openGL. The debug build is only required if you want debug wxWidgets itself, not if you want to debug an application build with wxWidgets (see the link below the table).
Note that there are more options, for a list of all do ../configure --help. If executable size matters, it makes sense to use a static build with stripped down functionality, e.g. you can remove all GUI parts.
Option what is does --with-gtk=X selects the GTK version X=2 or X=3 --with-opengl enables OpenGL support. Its off by default* --disable-shared builds static libs (ending *.a) instead of shared ones (ending *.so) --enable-debug enable or disable the adding of debug symbols. The debug libraries are much bigger** --prefix=[...] causes 'make install' to put the wxWidgets output file to a different location from the default /usr/local Default options from wx3.0 --enable-unicode makes a Unicode build (default set for newer than 2.9) --enable-monolithic makes a single library (normal for wxMSW, but unusual to need this on Linux)
- Discussion
- *: In some cases 'configure' ignored this setting or gave an error. Check that your system have the standard OpenGL libraries installed (they should be in the default installation ourdays). It might help to install 'freeglut3-dev'.
- **: you may want to read this post
Here is where we need to decide between the cases A) and B) (see above). In the following we use the example of building wxWidgets as: a shared library, with OpenGL, Unicode, using GTK3
Case A) Default install
../configure --with-gtk=3 --with-opengl
This will take a few seconds. In the end you get a summary of the selected options. 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 make -j3
Make from the same directory will start the build we just configured. The '-j' should be used to speed up the build if you have a multicore CPU. Using it without a number might crash your system, though. Make alone will use a single core.
When make is done without error the 'make install' command collects are required files, prepares all required links and stores the library ready to use into the systems default library folder. On Ubuntu this is 'usr/local/lib'.
sudo make install make clean
Make clean is optional, but should be used to delete the temporary files which are quite large.
On some systems you need to rebuild the library cache and make sure your new library is found everywhere in the system. Its a bit like registering a DLL in Windows. Its required on Ubuntu.
sudo ldconfig
Case B) Custom location install
The only difference for us to case A) is the use of the --prefix= option. The option sets the path where the libraries should be installed. If we would set the prefix to --prefix=/usr/local/lib we'd have Case A). So in your example we set the path to our local lib folder. As folder name we put "gtk3_so" to tell that its a GTK-3 version and a shared library. You could also add "u" for unicode or "gl" for OpenGL. 'Make install' will create that folder for us.
../configure --prefix=/home/$USER/wx/wxWidgets-3.1.3/lib/gtk3_so --with-gtk=3 --with-opengl
This will take a few seconds. In the end you get a summary of the selected options. 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.
The build works the same as in Case A):
make -j3
Make from the same directory will start the build we just configured. Use the '-j' option to to speed up the build on a multicore CPU. Using it without a number might crash your system, though. If you created several folders (build-gfk-3, build-gfk-3d, build-gfk-2gl. etc) you could also run make from the root directory after you have run all configure settings from its respective subfolder. That way you could leave the system alone to do all builds you need together.
make install
Note that here we do not need admin rights (no 'sudo'). 'Make install' will create the required data structure in the lib folder for us. It will also create the symlink to make wx-config work from the /home/$USER/wx/wxWidgets-3.1.3/lib/gtk3_so/bin folder. If all went well, remove the temp files with
make clean
Before you can use your new library on the command line add the location to the path. To keep it permanent you can add it to your ~/.bashrc file.
export PATH=$PATH;/home/$USER/wx/wxWidgets-3.1.3/lib/gtk3_so/bin
Your lib should show up with
wx-config --list
Test the installation
For a both installs type in the terminal (not the '//' and behind). It should work from any folder.
wx-config --version // e.g. yields "3.1.3"
wx-config --list // e.g. "Default config is gtk3-unicode.3.1"
The --version should be the version you just built. The --list option in case A) should list all version on the system.
If the program is not found or does nothing at all, it did not work and you need to go back to search for an error somewhere. First try to go to the 'bin' directory of your compiled library and try again.
/full/path/to/that/wx-config --version
You can do this for other --prefix installs, you can either do: If it works there, your Path is wrong or ldconfig did not work
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!