View source for Cross Compiling wxWidgets Applications on Linux

[[Category:User Documentation]]

If this document is helpful for you, or if you have questions or suggestions feel free to send me a mail or Personal Message.<br />

If there are errors or you miss something feel free to edit the document to make it better.

[[User:Jens|Jens]]

22:32, 27 March 2008 (CET)

--------------------

This document describes how to setup Code::Blocks to compile applications that use the wxWidgets toolkit for MS Windows from within Linux.<br />
I tested it on [http://www.debian.org/ debian] sid, but it should also work on other distributions.

=Needed software=
==Code::Blocks==
You can download prebuild binaries Code::Blocks from the [https://www.codeblocks.org/downloads/binaries download page].

If you prefer to compile Code::Blocks yourself, you have the choice between downloading the sourcecode of the actual release as tarball from the official [https://www.codeblocks.org/downloads/6 download page] or to download the newest version via [https://www.codeblocks.org/downloads/7 svn].<br />A guide to build Code::Blocks from svn can be found in the [[Nightly Cookbook]].

The newest svn-versions are also available as prebuild binaries made available by users.<br />
You can find links to the downloadpages in the actual posts in the [/index.php/board,20.0.html Nightly Builds] forum.
==MinGW32==
MingW32 is the cross-build version of the [http://www.mingw.org/ '''Min'''imalistic '''G'''nu for '''W'''indows] compiler suite (a port of the Gnu Compiler Suite for the MS Windows platform).<br />
It is part of many linux distributions.

On debian the basepackage is called ''mingw32'' and can be installed by typing
 sudo apt-get install mingw32
at the command-line.<br />
It's up to you to find out the name of the package and install it using your preferred package-manager or either compile it by hand.
==wxWidgets cross-build==
For debian-users I have made prebuild binary packages available on my [http://apt.jenslody.de/ server]. I guess they are also usable on Ubuntu, but you have to try it yourself.

I don't know if there are downloadable packages available in/for other distros, but you can build it on your own.

You can download the source-code either from my [http://apt.jenslody.de/pool/ server's software pool] or from the [http://www.wxwidgets.org/ wxWidgets] download page.

Unpack the sources and type configure it with
 ./configure prefix=/usr/i586-mingw32msvc --host=i586-mingw32msvc --enable-unicode --build=`./config.guess` --disable-shared
The prefix depends on your MinGW32 installation, either does the host. The other switches can be changed as you prefer it, with oine exception (at the moment):<br />
I wasn't able to build any application with the shared version of wxWidgets and to run it on MS WIndows with the native dll's. It only works if it is statically linked or you distribute the needed dll's that can be found in '''/usr/i586-mingw32msvc/lib/''' and put them into the executables directory. Putting them into the search path might interfere with existing wxWidgets dll's on windows.

You can see the available switches with
 ./configure --help


If everything wents right you get a message like this:

 Configured wxWidgets 2.8.8 for `i586-pc-mingw32msvc'
 
   Which GUI toolkit should wxWidgets use?                 msw
   Should wxWidgets be compiled into single library?       no
   Should wxWidgets be compiled in debug mode?             no
   Should wxWidgets be linked as a shared library?         no
   Should wxWidgets be compiled in Unicode mode?           yes
   What level of wxWidgets compatibility should be enabled?
                                        wxWidgets 2.4      no
                                        wxWidgets 2.6      yes
   Which libraries should wxWidgets use?
                                        jpeg               builtin
                                        png                builtin
                                        regex              builtin
                                        tiff               builtin
                                        zlib               builtin
                                        odbc               no
                                        expat              builtin
                                        libmspack          no
                                        sdl                no

Now you can build the libraries with
 make
 make install

If you use my binaries you should be able to call <code>wx-config</code> directly.<br />
As test you can run <pre>wx-config --list</pre>.
The ouput should look like
    Default config is gtk2-unicode-release-2.8
 
  Default config will be used for output
 
  Alternate matches:
    base-unicode-release-2.8
 
  Also available in /usr:
    i586-mingw32msvc-msw-unicode-debug-2.8
    i586-mingw32msvc-msw-unicode-release-2.8
    i586-mingw32msvc-msw-unicode-release-static-2.8

You can see the cross-compile configurations starting with ''i586-mingw32msvc-msw''.

If you don't see any cross-compile configurations you have to use the appropriate wx-config directly:
 /usr/i586-mingw32msvc/lib/wx/config/i586-mingw32msvc-msw-unicode-release-static-2.8 --list
(The instruction may differ according to your configuration.)<br />
If the output shows your cross-build targets, everything is okay. If not something went wrong with compiling your wxWidgets cross-libraries.

In the further part of this document I'll use the paths I used in the example configure-line.

=Preparing Code::Blocks=
If everything is installed you have to prepare Code::Blocks for cross-compiling.

Therefore you need a special compiler based on '''''GNU GCC compiler'''''
==''Create'' Compiler==

*Open '''''Settings -> Compiler and Debugger ... -> Global compiler settings'''''.
*Chose '''''GNU GCC compiler'''''.
*Click <span style="border:1px solid black;background-color:#ddd;">Copy</span>.
*Give your new Compiler a meaningful name.
[[Image:DuplicateCompiler.png|thumb|none|Duplicate Compiler]]

*Chose the cross-compiler.
==Fix Search directories==
*Open the <span style="border:1px solid black;background-color:#ddd;">Search directories</span> notebook.
*Change the search directory for the <span style="border:1px solid black;background-color:#ddd;">Compiler</span> to
 /usr/i586-mingw32msvc/include/
[[Image:SearchDirsCompiler.png|thumb|none|Search Directories -> Compiler]]

*for the <span style="border:1px solid black;background-color:#ddd;">Linker</span> to
 /usr/i586-mingw32msvc/lib/
[[Image:SearchDirsLinker.png|thumb|none|Search Directories -> Linker]]

*and the <span style="border:1px solid black;background-color:#ddd;">Resource Compiler</span> also to
 /usr/i586-mingw32msvc/include/
[[Image:SearchDirsResources.png|thumb|none|Search Directories -> Resource Compiler]]
==Fix Toolchain Executables==
*Open the <span style="border:1px solid black;background-color:#ddd;">Toolchain executables</span> notebook.
*Change the <span style="border:1px solid black;background-color:#ddd;">Program Files</span> as follows:
:*'''C Compiler''' to:
:<pre>i586-mingw32msvc-gcc</pre>
:*'''C++ Compiler''' and '''Linker for dynamic libs''' to:
:<pre>i586-mingw32msvc-g++</pre>
:*'''Linker for static libs''' to:
:<pre>i586-mingw32msvc-ar</pre>
:*'''Debugger''' to:
:<pre>i586-mingw32msvc-gdb</pre>
:*'''Resource compiler''' to:
:<pre>`wx-config --host=i586-mingw32msvc --rescomp`</pre>
:*Leave '''Make''' unchanged
[[Image:ToolchainExecutables.png|thumb|none|Toolchain executables]]

One word to the debugger executable: there is no cross-debugger available in the MinGW-suite !<br />
But for rudimentary debugging we can use the MS Windows version of the ''gdb''-debugger avaible on the [http://www.mingw.org/ MinGW] download site.

But debugging works not reliable, I think it's because there are some ''ifdef'''s in the Code::Blocks sources for the debugger-plugin dealing with differences between the linux and the MS Windows versions of ''gdb'' and the different application structure. Even if we use a MS WIndows executable as debugger, Code::Blocks believes it works on linux (and that's of course right) and is therefore compiled for the linux ''gdb.''

There is also a real cross-debugger for MS WIndows applications available, that belongs to [http://www.winehq.org/ wine], but the syntax is not compatible with the one of ''gdb,'' even if it is possible to use ''gdb'' as backend for ''winedbg''.

I will come back to the debugger and how it can be called (a shell-script) later in this document.
=Setting up your project=
You can of course use a working wxWidgets-project, but for testing I think the best way is to use the wizard and create a brand-new project.

==Creating a new build target==
If you have opened your project in Code::Blocks, go to the '''Projects''' tab in the '''Manager''' and right-click it to prepare it for cross-compiling.

Chose '''Properties..'''. from the context menu and switch to the <span style="border:1px solid black;background-color:#ddd;">Build targets</span>-tab.

Select one of the build targets (I used '''Release''' for this example), click the <span style="border:1px solid black;background-color:#ddd;">Duplicate</span>-button and give it a new name (WinRelease in my case).
[[Image:PropertiesDuplicate.png|thumb|none|Duplicate build target]]

Change the '''Output filename''' from '''bin/Release/<filename>''' to '''bin/WinRelease/<filename>.exe''', and uncheck at least '''Auto-generate filename extension'''.
[[Image:BuildTargets.png|thumb|none|Adapt settings of build target]]
==Fixing build options==
*In the '''Build options''' of the project you have to move <code>`wx-config --cflags`</code> from the global '''Compiler settings -> Other options''' to the one for the standard build targets ('''Debug''' and '''Release''').<br />
:Do the same for '''Linker Settings -> Other linker options'''.

*To make it clear the '''Other options'''-tabs of the '''Compiler settings''' and '''Linker settings''' belonging to the whole project have to be empty (or only include settings that are valid for the Linux '''and''' the MS Windows targets).

*Change the compiler for '''WinRelease''' from '''GNU GCC compiler''' to '''Mingw GNU GCC Cross-Compiler for Windows''' or however you called the cross-compiler.

*The appropriate calls to '''wx-config''' for the '''WinRelease''' must have the parameter: '''--host=i586-mingw32msvc''' included and should have the parameter '''--static''' set also.<br />
:Until now I haven't been able to make a cross-compiled program run on MS Windows if I did not use the static libraries.

* The line in '''Linker Settings -> Other options''' should look like that:
 `wx-config --host=i586-mingw32msvc --static --cflags`
[[Image:CompilerSettings.png|thumb|none|Compiler settings]]

* The line in '''Linker Settings -> Other linker options''' should look like that:
 `wx-config --host=i586-mingw32msvc --static --libs`
[[Image:LinkerSettings.png|thumb|none|Linker settings]]

If the wx-config-command does not find the correct wxWidgets configuration, you can also add a '''--prefix=/usr/i586-mingw32msvc''' or maybe another prefix if you use self-compiled libraries (it should be the same you used for '''./configure''').

==Compile==
Not much to say here.

If everything went right, you should have a real MS Windows-application in your output directory:
 file bin/WinRelease/test.exe
 bin/WinRelease/test.exe: MS-DOS executable PE  for MS Windows (GUI) Intel 80386 32-bit
If you want to run it on MS Windows you need '''mingwm10.dll''' in the same directory or at any other place in the search path.<br />
It's part of the '''mingw32-runtime'''-package and can be found (gzipped) in '''/usr/share/doc/mingw32-runtime/''' (at least on debian systems).

You can create console-projects in a similar way  without using '''wx-config''' of course.

=Running on Linux=
==Normal run==
To run your application on Linux you will need the [http://www.winehq.org/ wine]-package.

To start a MS WIndows executable from the console (or from within Code::Blocks) you need the '''binfmt-support'''-package or however it is called in your distro.

If you run your test application it should look like this one:
[[Image:AboutBox.png|thumb|none|Dialog based example]]
==Debugging==
===Known limitations===
Debugging MS Windows apps with Code::Blocks works, but it does not work reliable.

I think one problem is that '''gdb''' has a slightly different syntax on '''Linux''' and '''MS Windows'''. '''Code::Blocks''' is aware of this and therefore uses different instructions when running '''gdb''' on '''Linux''' and on '''MS Windows'''.<br />
Therefore there are some <code>#ifdef</code>'s in source code.

The problem is that '''Code::Blocks''' on '''Linux''' is compiled for ... right '''Linux'''.<br />
It does not know anything about special instructions for '''MS WIndows''' to use while debugging.

Annother problem might be the fact that [http://www.winehq.org/ wine] normally uses it own dll's and that its api is not 100% compatible with the original '''MS Windows'''-api.<br />
It might be possible to do some tweaking, or to use real '''MS Windows''' dll's, but that can lead to licensing problems and there is of course no guarantee that it works (better) in all cases.

===Setting up the debugger===
Nevertheless it is possible to debug '''MS Windows''' applications from within '''Code::Blocks''':

Download a recent '''gdb'''-package (for '''MS Windows''' of course) from [http://www.mingw.org/ www.mingw.org/] and unzip to any directory you want.<br />
I put it into:
 ~/.wine/drive_c/MinGW/
There should be at least a <code>bin</code>-subdirectory now that contains '''gdb.exe'''.<br />
Typing
 ~/.wine/drive_c/MinGW/bin/gdb.exe -v
at the console should lead to something like this:
 GNU gdb 6.7.50.20071127
 Copyright (C) 2007 Free Software Foundation, Inc.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
 and "show warranty" for details.
 This GDB was configured as "i686-pc-mingw32".
 Wine exited with a successful status

The easiest way to use '''gdb.exe''' from within Code::Blocks is to create a simple shell-script (I called it '''i586-mingw32msvc-gdb''') :
 #!/bin/sh
 
 wine /home/jens/.wine/drive_c/MinGW/bin/gdb.exe "$@"

You have to fix the path inside the script to point to your '''gdb.exe'''.

Make the script executable and place it in <code>/usr/bin</code>.
 chmod 755 i586-mingw32msvc-gdb
 sudo chown root.root i586-mingw32msvc-gdb
 sudo mv i586-mingw32msvc-gdb /usr/bin

If you now run:
 i586-mingw32msvc-gdb -v
from the console you should get the same output as above when calling '''gdb.exe''' directly.

You now have to put the name of the script in the appropriate text-box in '''Toolchain executables''' as described [[#Fix_Toolchain_Executables|above]].

The debugger can be used as the native '''gdb''' for '''Linux''' from within '''Code::Blocks'''.

Happy debugging.

=(External) Links=

Here are some links that contain interesting articles and/or discussions about cross-compiling.

They are surely not complete and they are not in any special order.

[http://en.wikipedia.org/wiki/Cross_compiler http://en.wikipedia.org/wiki/Cross_compiler]<br />
[http://www.wxwidgets.org/wiki/index.php/Cross-Compiling_Under_Linux http://www.wxwidgets.org/wiki/index.php/Cross-Compiling_Under_Linux]<br />
[https://wiki.codeblocks.org/index.php?title=Code::Blocks_and_Cross_Compilers https://wiki.codeblocks.org/index.php?title=Code::Blocks_and_Cross_Compilers]<br />
[http://gcc.gnu.org/wiki/Building_Cross_Toolchains_with_gcc http://gcc.gnu.org/wiki/Building_Cross_Toolchains_with_gcc]<br />
[/index.php/topic,7978.0.html /index.php/topic,7978.0.html]<br />
[/index.php/topic,3343.0.html /index.php/topic,3343.0.html]<br />
[/index.php/topic,6876.0.html /index.php/topic,6876.0.html]<br />
[/index.php/topic,7454.0.html /index.php/topic,7454.0.html]<br />