Difference between revisions of "Compiling and getting started"

From WxWiki
Jump to: navigation, search
(Undo revision 11411 by Tierra (talk))
m (Before starting)
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
Back to [[Install#Linux|Install]]<br>
 
Back to [[Install#Linux|Install]]<br>
 +
 
This is a guide to help you get started quickly and easily on Linux with wxWidgets built from source.
 
This is a guide to help you get started quickly and easily on Linux with wxWidgets built from source.
  
 
== Before starting ==
 
== Before starting ==
 +
wxWidgets is a cross-platform system 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)
 +
 +
:<syntaxhighlight lang="DOS">
 +
    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
 +
                                                [...]
 +
</syntaxhighlight>
 +
:''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. <br>
 +
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-config --list' would not run or only find one of your installations.
 +
  
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.
+
'''Notes'''<br>
 +
: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)
  
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.
+
:There is an installation help file in every source archive under <code>doc/gtk/install.md</code> which also contains some additional information.
  
== wxWidgets ==
+
: ''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.''
  
Download the wxWidgets source archive, the tar.bz2 one as this has the correct line-endings, from https://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.
+
[[#top|top]]
  
Then the following steps are done in a terminal:
+
== 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
  
<syntaxhighlight lang="cpp">cd /path/to/wxWidgets-3.0.x # adapt path as needed
+
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
mkdir gtk-build # or any other name you fancy
+
sudo apt install libgtk2.0-dev           
 +
sudo apt install libgtk-3-dev
 +
 
 +
 
 +
[[#top|top]]
 +
 
 +
== 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 [[#Before starting|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 <code>/home/$USER/wx</code>. Remember to adapt the path accordingly.
 +
 
 +
[[#top|top]]
 +
 
 +
== Building the library==
 +
'''TL;DR''': if you are in a hurry and know the details here is the default for case A) (see [[#Before starting|above]])
 +
<syntaxhighlight lang="bash">
 +
cd ~/wx/wxWidgets-3.1.3   
 +
mkdir gtk-build             # the name is not really relevant
 
cd gtk-build
 
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
 
</syntaxhighlight>
 
</syntaxhighlight>
  
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.
+
'''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.
 +
<syntaxhighlight lang="bash">
 +
cd ~/wx/wxWidgets-3.1.3   
 +
mkdir gtk-build            # the name is not really relevant, use what you like
 +
cd gtk-build
 +
</syntaxhighlight>
 +
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.
 
Then call ../configure. Note the '..'; the configure script is in the parent dir.
For wx2.8 you might do:
+
Here are a few examples. Do not type the comments including and after "//"
<syntaxhighlight lang="cpp">../configure --enable-unicode --enable-debug</syntaxhighlight>
+
<syntaxhighlight lang="bash">
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.
+
../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
 +
</syntaxhighlight>
 +
 
 +
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.  
  
The options you pass to configure at this point will determine what build you get.
 
 
:{| class=wikitable
 
:{| class=wikitable
! option !! what is does
+
! 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
+
| --enable-debug   || enable or disable the adding of debug symbols. The debug libraries are much bigger**
 
|-
 
|-
| --enable-unicode || makes a Unicode build (automatically set for newer than 2.9)
+
| --prefix=[...]  || causes 'make install' to put the wxWidgets output file to a different location from the  default <tt>/usr/local</tt>
 
|-
 
|-
| --with-opengl    || enables OpenGL support
+
| colspan="2"| Default options from wx3.0
 
|-
 
|-
| --disable-shared || builds static libs instead of shared ones
+
| --enable-unicode || makes a Unicode build (default set for newer than 2.9)
 
|-
 
|-
| --prefix=[...] || makes wxWidgets install to a different location from the  default <tt>/usr/local</tt>
+
| --enable-monolithic|| makes a single library (normal for wxMSW, but unusual to need this on Linux)
 
|-
 
|-
 
|}
 
|}
: Note: if you wonder why the <code>--enable-debug</code> option is not listed, you may want to read [http://wxwidgets.blogspot.com/2009/09/debug-build-changes-in-wx3.html this post]
+
: Discussion
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'.
+
: *: 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 [http://wxwidgets.blogspot.com/2009/09/debug-build-changes-in-wx3.html this post]
  
For a list of all possible options, do ''../configure --help''. However most of these are very rarely needed.
+
Here is where we need to decide  between the cases A) and B) (see [[#Before starting|above]]). In the following we use the example of building wxWidgets as: a shared library, with OpenGL, Unicode, using GTK3
  
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.
+
'''Case A)''' Default install <br>
 +
../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 -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.
  
<syntaxhighlight lang="cpp">make</syntaxhighlight>
+
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'.
or
+
sudo make install
<syntaxhighlight lang="cpp">make -j</syntaxhighlight>
+
make clean
: 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.
+
Make clean is optional, but should be used to delete the temporary files which are quite large.
  
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:
+
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
  
<syntaxhighlight lang="cpp">make install</syntaxhighlight>
 
  
By default wxWidgets will be installed to /usr/local/
+
'''Case B)''' Custom location install <br>
 +
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.
  
On some systems it is then necesary to run ''ldconfig''.
+
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 <code>/home/$USER/wx/wxWidgets-3.1.3/lib/gtk3_so/bin</code> 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
 +
 +
Note that a common use of '--prefix=' is to create an 'in situ' install. If you configure with e.g.:
 +
../configure --prefix=$(pwd)
 +
the resulting 'install' will be in the build dir. There is no need to 'make install'. To access the resulting install, just point to its wx-config, either in your terminal's $PATH as above, or by calling e.g.
 +
<syntaxhighlight lang="bash">
 +
/full/path/to/build-dir/wx-config --cxxflags --libs
 +
</syntaxhighlight>
 
[[#top|top]]
 
[[#top|top]]
  
 
== Test the installation ==
 
== Test the installation ==
For a standard install, open a terminal and type
+
For both installs, type in the terminal (not the comments starting with '//'). It should work from any folder.
  
<syntaxhighlight lang="cpp">wx-config --version</syntaxhighlight>
+
<syntaxhighlight lang="bash">
 +
wx-config --version             // e.g. yields "3.1.3"
 +
wx-config --list                // e.g. "Default config is gtk3-unicode.3.1"
 +
</syntaxhighlight>
 +
The --version should be the version you just built.
 +
The --list option in case A) should list all versions installed on the system.
  
It should be the version you just built. If it isn't, or for other --prefix installs, you can either do:
+
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.
<syntaxhighlight lang="cpp">/full/path/to/that/wx-config --version</syntaxhighlight>
+
<syntaxhighlight lang="bash">/full/path/to/that/wx-config --version</syntaxhighlight>
or prepend that dir to your PATH e.g.
+
If it works there, either your Path is wrong or ldconfig did not work
<syntaxhighlight lang="cpp">PATH=/full/path/to/that/wx-config:$PATH</syntaxhighlight>
 
  
 
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':
 
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':
<syntaxhighlight lang="cpp">cd gtk-build/samples/minimal
+
<syntaxhighlight lang="bash">cd gtk-build/samples/minimal
 
make
 
make
 
./minimal</syntaxhighlight>
 
./minimal</syntaxhighlight>
Line 85: Line 194:
 
The tool wx-config allows you to quickly build wxWidgets apps:
 
The tool wx-config allows you to quickly build wxWidgets apps:
  
<syntaxhighlight lang="cpp">
+
<syntaxhighlight lang="bash">
 
g++ widgetTest.cpp `wx-config --cxxflags --libs` -o widgetTest
 
g++ widgetTest.cpp `wx-config --cxxflags --libs` -o widgetTest
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 15:49, 5 January 2021

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 system 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-config --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.md which 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.

top

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


top

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.

top

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

Note that a common use of '--prefix=' is to create an 'in situ' install. If you configure with e.g.:

../configure --prefix=$(pwd)

the resulting 'install' will be in the build dir. There is no need to 'make install'. To access the resulting install, just point to its wx-config, either in your terminal's $PATH as above, or by calling e.g.

/full/path/to/build-dir/wx-config --cxxflags --libs

top

Test the installation

For both installs, type in the terminal (not the comments starting with '//'). 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 versions installed 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

If it works there, either 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.

top

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'.

top

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!

top