This is a tutorial targeted towards users of the Codeblocks IDE. If you ever wanted to create a wxWidgets project and your IDE is Codeblocks then this post is for you. If you have no idea what I am talking about, but still you want to create GUI programs with a free and open-source library and IDE then read on and I will explain along the way.
Tutorial Prerequisities
- The reader should be familiar with the concept of an IDE
- The reader should download both the Codeblocks IDE and the wxWidgets library (way is mentioned in the tutorial)
Tutorial Goals
- To familiarize the reader with the Codeblock IDE
- To enable the reader to configure the usage of wxWidgets with Codeblocks
Tutorial Body
First of all we need to download and compile the wxWidgets library. If you have done so already you can skip this section.
Go to the wxWidgets download page and choose the latest stable release. At the time of the writing of this guide it is 2.8.10. I would recommend to download wxALL so you can compile it depending on your OS and also later have the option to compile the library for another OS without needing to re-download.
Unzip the folder you downloaded and go to the build directory. Inside the build directory you will find various other directories if you downloaded wxALL. If you downloaded it for just a specific OS then you will find that specific OS's directory inside. If you are using windows open up the command prompt "cmd" from Start->Run. For other OSes the directions are similar but I will focus on Windows. It is possible to understand what to do by just seeing what needs to be done in Windows. So, navigate to the wxWidgets folder you just downloaded and go to build->msw, by using the "cd" command. In here the makefiles to create the library are located.
Assuming you are using the mingw32 compiler, after having navigated inside the directory just type:
mingw32-make -f makefile.gcc BUILD=release SHARED=1 MONOLITHIC=1 UNICODE=1
Additionally if you add a "clean" in the end of the command you are clearing and deleting everything that has been compiled with the same settings you gave at the command. It is always a good idea to clean before compiling. So
mingw32-make -f makefile.gcc BUILD=release SHARED=1 MONOLITHIC=1 UNICODE=1 clean
would clean all the compiled libraries and object files of the specific build.
I will now explain the command to compile the library in more detail. What you do is that you are basically telling the mingw32 compiler to compile the library based on the instructions located in makefile.gcc. You are also giving the compiler some options. These are:
- BUILD
- release - This means that this will be a release build
- debug - This means that this will be a debug build. You need the debug build to be able to use a debugger when creating wxidgets programs
- SHARED
- 1 - This means that the library will be dynamically compiled. So in windows it would produce dlls that would need to be distributed along with the program. When you compile with a dynamic library the executable of the program is always smaller in size but you have to distribute the .dlls along with it.
- 0 - This means that the library will be statically compiled. This produces just a static library which you do not have to distribute along with your program as opposed to the .dll mentioned above.
- MONOLITHIC
- 1 - You are telling the compiler to make a monolithic library. In other words you are telling it to compile it all in just one library file. Which means that in the end you will get just one import library (windows example: libwxmsw28.a) and if you got a dll build just one dll. This makes it easier to create and distribute projects but as expected you end up with bigger library files.
- 0 - The compiler understands you don't want a monolithic library. So it just creates many component libraries and gives you the choice to link to only the parts of the wxWidgets library you need for your application. Makes it easier to have modular programs if you use this option
- UNICODE
- 1 - Well this option is pretty much self-explanatory. This adds unicode writing ability to your wxWidgets programs. In my personal opinion this is a MUST for every modern program. So I would suggest you have this option at 1.
- 0 - This disables unicode and the only encoding you can use in your program is ANSI. Highly discouraged. Unless you want a program that can only use the English language and have no hopes of internationalization.
I would recommend choosing your settings according to your preferences of course but always make at least 2 library builds. One for debug and one for release mode. So first type:
mingw32-make -f makefile.gcc BUILD=release SHARED=1 MONOLITHIC=1 UNICODE=1
and then:
mingw32-make -f makefile.gcc BUILD=debug SHARED=1 MONOLITHIC=1 UNICODE=1
The result of compiling is some .a and .dll files depending on the compiling options. Depending on the options you used when compiling the file name of the library files also differs. For example debug files have a 'd' suffix and Unicode files have a 'u' suffix. So "libwxmsw28ud.a" is a Unicode debug build. What I would recommend is to have the two library builds (debug and release) in two separate directories. For example something like this for windows:
This would allow you to both easily remember the options you used when compiling the library but also to easily link to the 2 separate library builds from your program.
That was it. You now have the wxWidgets library downloaded and compiled in your computer. Let's assume that the directory where you have it downloaded it is "wxWidgets-2.8.10" and the directories where you keep the two compiled builds are like the ones I mentioned above. Now is time to download Codeblocks if you don't already have it. Choose the download depending on your OS as usual. After installing go to File->New->Project.
There choose an Empty Project. There is actually a wxWidgets project option which by using a wizard guides you through setting up a wxWidgets project but in this tutorial I want to show all the project options in Codeblocks that you need to tweak to link to the WX library so doing it the automatic way would make no sense.
Now in order for your program to get linked to wxWidgets you need to configure some options. Just for testing and in case you don't have a program of your own you can try the wxWidgets hello world program.
Go to Project->Build Options. There by clicking on the project name you can get the general settings for both the debug and release build. Just under it you can find the release and debug build options which are separate. So these are the options that you have to configure:
- BOTH BUILDS(Click on the project name)
- Compiler Settings->#defines Add the following:
__GNUWIN32__
__WXMSW__
WXUSINGDLL
wxUSE_UNICODE
Replace __WXMSWM__ with the corresponding OS you are compiling for, provided that you have the library for it. Also if you are not using dll don't write WXUSINGLDLL, same goes for Unicode. Basically the #defines are self-explanatory. - Search directories->Compiler. Press "ADD" and add:
C:\wxWidgets-2.8.10\include
C:\wxWidgets-2.8.10\contrib\include - Search directories->Resource Compiler:. Press "ADD" and add:
C:\wxWidgets-2.8.10\include
- DEBUG
- Compiler Settings->#defines. Add: __WXDEBUG__
- Linker Settings->Link Libraries Press "ADD" to add the libraries to link to. Assuming you followed the convention I mentioned above you would add:
C:\wxWidgets_2.8.10_DEBUG_SHARED_MONOLITHIC_UNICODE\libwxmsw28ud.a - Search directories->Compiler. Assuming you are using windows, add:
C:\wxWidgets_2.8.10_DEBUG_SHARED_MONOLITHIC_UNICODE\mswud - Search directories->Linker. Add:
C:\wxWidgets_2.8.10_DEBUG_SHARED_MONOLITHIC_UNICODE - Search directories->Resource Compiler. Again assuming you use windows add:
C:\wxWidgets_2.8.10_DEBUG_SHARED_MONOLITHIC_UNICODE\mswud
- RELEASE
- Linker Settings->Link Libraries. Add the following libraries:
C:\wxWidgets_2.8.10_RELEASE_SHARED_MONOLITHIC_UNICODE\libwxmsw28u.a - Search directories->Compiler. Assuming you are using Windows, add:
C:\wxWidgets_2.8.10_RELEASE_SHARED_MONOLITHIC_UNICODE\mswu - Search directories->Linker. Add:
C:\wxWidgets_2.8.10_RELEASE_SHARED_MONOLITHIC_UNICODE - Search directories->Resource compiler. Assuming you are using Windows, add:
C:\wxWidgets_2.8.10_RELEASE_SHARED_MONOLITHIC_UNICODE\mswu
This was it. Now your codeblocks program is properly linked with the wxWidgets library that you compiled. Just press "F9" to compile and run your new GUI program. There are some additional libraries of wxWidgets that you can link to (such as openGL and wxWidgets) but these will not be covered by this tutorial. As always in case there are any questions/remarks or corrections about this tutorial you can email me at lefteris *at* realintelligence.net and I will try to answer your questions as thorougly as possible.