Difference between revisions of "Compiling and getting started"

From WxWiki
Jump to: navigation, search
(Major update; ubuntu 8.04 is no longer the most likely version to be used :p)
Line 3: Line 3:
 
== Before starting ==
 
== Before starting ==
  
Install all necessary build tools, including g++ and autotools. (On Ubuntu, you will want to install package build-essential)
+
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.
  
You will also need gtk+ (don't forget to install the -dev package if your distro uses them). For Ubuntu 8.04 this will be libgtk-2.0-dev.
+
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.
On lucid (10.4) it is libgtk2.0-dev.
 
 
 
It is recommended to use at least GTK+ 2.2.3, and some features are only available
 
when using more recent version, like GTK+ 2.8.
 
  
 
== wxWidgets ==
 
== wxWidgets ==
  
Download the wxWidgets source archive from http://www.wxwidgets.org/downloads/ and expand 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.
+
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 on the terminal.
+
Then the following steps are done in a terminal:
  
 
<source>cd /path/to/wxWidgets-3.0.x # adapt path as needed
 
<source>cd /path/to/wxWidgets-3.0.x # adapt path as needed
mkdir gtk-build
+
mkdir gtk-build # or any other name you fancy
 
cd gtk-build
 
cd gtk-build
 
</source>
 
</source>
  
we create a new folder to build from, this enables us to have many wxWidgets builds, for instance a debug and a release one, or a Unicode and an ANSI one, or a static and a shared one, etc.
+
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 you will need to call configure with something like
+
Then call ../configure. Note the '..'; the configure script is in the parent dir.
<source>../configure --enable-unicode</source>
+
For wx2.8 you might do:
 +
<source>../configure --enable-unicode --enable-debug</source>
 +
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.
  
 
However, if you want to compile wxWidgets on a 64-bit version of Linux in such a way that the library can be linked to both statically and dynamically, then you want to add the ''-fPIC'' flag to the ''configure'' call. That is done in the following way:
 
However, if you want to compile wxWidgets on a 64-bit version of Linux in such a way that the library can be linked to both statically and dynamically, then you want to add the ''-fPIC'' flag to the ''configure'' call. That is done in the following way:
Line 35: Line 33:
 
<tr><td>--with-opengl</td><td>enables OpenGL support</td></tr>
 
<tr><td>--with-opengl</td><td>enables OpenGL support</td></tr>
 
<tr><td>--disable-shared</td><td>builds static libs instead of shared ones</td></tr>
 
<tr><td>--disable-shared</td><td>builds static libs instead of shared ones</td></tr>
<tr><td>--prefix=[...]</td><td>makes wxWidgets be installed in another location than default /usr/local</td></tr>
+
<tr><td>--prefix=[...]</td><td>makes wxWidgets install to a different location from the  default /usr/local</td></tr>
 
</table>
 
</table>
  
(for a list of all possible options, write ''../configure --help'')
+
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.
  
If it stops saying it can't find a package, install it (with -dev packages if any) and run configure again. When it is done without errors, you are ready to build.
+
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.
  
 
<source>make</source>
 
<source>make</source>
 +
or
 +
<source>make -j</source>
  
When the build is done, and if no error occured, you can now install it
+
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:
  
<source>sudo make install</source>
+
<source>make install</source>
  
Enter your password as needed. wxWidgets will be installed in /usr/local/
+
By default wxWidgets will be installed to /usr/local/
  
On some systems it is also necesary to run
+
On some systems it is then necesary to run ''ldconfig''.
''sudo ldconfig'' at this point.
 
  
== Test installation ==
+
== Test the installation ==
Open a terminal and type
+
For a standard install, open a terminal and type
  
 
<source>wx-config --version</source>
 
<source>wx-config --version</source>
  
It should be the version you just built.
+
It should be the version you just built. If it isn't, or for other --prefix installs, you can either do:
 
+
<source>/full/path/to/that/wx-config --version</source>
If it is not:
+
or prepend that dir to your PATH e.g.
<blockquote>
+
<source>PATH=/full/path/to/that/wx-config:$PATH</source>
try running
 
  
''which wx-config''
+
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':
 +
<source>cd gtk-build/samples/minimal
 +
make
 +
./minimal</source>
  
and see if it is the one you just installed (if you did not change the default value, you installed /usr/local/bin/wx-config)
+
'minimal' and 'widgets' are respectively the simplest and the most complete samples.
 
 
if you get something like ''/usr/bin/wx-config'' while you installed ''/usr/local/bin/wx-config'', it means there is another version of wxWidgets installed somewhere else, probably installed by the system. You can quickly get it out the way with a hacky command like ''sudo mv /usr/bin/wx-config /usr/bin/wx-config-old1''.
 
</blockquote>
 
 
 
Then, to test more in depth, you can look at the samples. Open the Samples folder located at wxGTK-2.8.x/gtk-build/samples (be careful : wxGTK-2.8.4/samples contains the source code, while wxGTK-2.8.4/gtk-build/samples contains the makefiles for your system. for building samples, you will want to cd into the latter, while to study the code you will want to open the former)
 
 
 
cd into one of the samples, and type ''make''. You can then open the sample to see wxWidgets in action.
 
  
 
== Building apps with wxWidgets ==
 
== Building apps with wxWidgets ==
The tool wx-config allows you to quickly build wxWidgets apps
+
The tool wx-config allows you to quickly build wxWidgets apps:
  
 
<source>
 
<source>
g++ `wx-config --cppflags` `wx-config --libs` widgetTest.cpp
+
g++ widgetTest.cpp `wx-config --cxxflags --libs` -o widgetTest
 
</source>
 
</source>
  
wx-config --cppflags returns flags necessary to compilation, wx-config --libs returns flags necessary to 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. (How to use g++ is beyond the scope of this document)
+
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]].
+
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 ==
 
== Running wxWidgets projects ==
Line 90: Line 88:
 
If when running a wxWidgets app you get an error like:
 
If when running a wxWidgets app you get an error like:
  
''./a.out: error while loading shared libraries: libwx_gtk2_aui-2.8.so.0: cannot open shared object file: No such file or directory ''
+
''./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 :
 
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 :

Revision as of 05:19, 27 December 2014

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.

However, if you want to compile wxWidgets on a 64-bit version of Linux in such a way that the library can be linked to both statically and dynamically, then you want to add the -fPIC flag to the configure call. That is done in the following way:

../configure --enable-unicode CFLAGS="-fPIC" CXXFLAGS="-fPIC"

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

--enable-unicodemakes a Unicode build
--with-openglenables OpenGL support
--disable-sharedbuilds 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

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!