Setting up Qt on the Mac

On the day of WWDC all people could think about was the new G5 PowerMacs, or Mac OS X 10.3 “Panther.” While most news sites drowned in WWDC coverage, and then the whole debate over benchmarks, it was quite easy to miss this little gem. Trolltech released Qt 3.1.2 for OSX last Monday.

In all honesty, this piece of news is what I’m most excited about more so than anything that went on at WWDC, this includes those shiny new G5 systems or even the 64 bit MacOSX. The reason for this is because I believe that the Qt library has the greatest effect on the way I develop software on the Mac platform, and perhaps other developers will see it this way too.


I promise to make this a brief history lesson. I’ve been programming as a hobbyist for the past 5 years, the latter 2 years and to date I am programming professionally. I started out with Windows, teaching myself C++ and using MFC to design applications. Last year I had my first encounter with a modern Macintosh computer. I purchased an iMac2 flat panel in hopes of learning to develop for this platform. Between Carbon, Cocoa, and even Metrowerks’ PowerPlant, I found this transition more trouble than it was worth for just a hobby that I might not make a career out of. So I set it down for a year now. This past April and May I revisited Linux, in particular Mandrake and Gentoo distributions, and continued my programming endeavors with Qt. Coming from an MFC background, I found Qt to be a very smooth transition. Then in June I made a come back to the Mac platform by purchasing an iBook. What prompted me to do this was that I had upgraded my iMac to OSX 10.2 and finally it was in a usable state that I felt comfortable with, albeit some issues still existed. I tried to un-brainwash myself from years of Windows programming in order to accept Objective-C and Cocoa. But as soon as I heard that Trolltech was going to release an updated Qt library for MacOSX, I abandoned Cocoa altogether.

How to get it

Now to get down to business. To download Qt/Mac Free Edition, visit Trolltech’s website here. What do you get in this package?

– The source code to the Qt library.
– Documentation in HTML format (Qt Assistant is also included for additional documentation).
– Helper applications such as QT Designer, Assistant, Linguist, and command line tools such as qmake. qmake will be a very important tool, as you’ll see later on.
– Plenty of example apps and their source.

I didn’t actually have to wait for Trolltech to make this release, as Qt has been available for OSX for some time now. It can be obtained through Fink, but it does require that the user install an X server first. I did not bother to make this attempt because I didn’t see the need to since I have a Linux box right next to me. The beauty of this Qt/Mac distribution from Trolltech is that it DOES NOT require an X server at all! Qt/Mac uses Carbon internally the same way Qt for Windows uses an API native to Windows. Trolltech had made Qt version 3.x for MacOS in the past but only with a commercial license, and if there was a free edition it was from the 2.x version. That’s the significance of this new Qt/Mac release. It brings Qt for MacOS up-to-date and introduces the dual license structure: the free, GPL’ed, edition is exactly the same as the commercial edition in terms of source code.

Setting up

The installation document covers the procedure quite well, however there is one little problem that I encountered, and is repeatable. More on that in a minute. The first thing to do is obviously unpack the package. The install doc suggested I unpack everything into /usr/local/qt and that’s exactly what I did. But since this folder is outside of my home directory I had to use the “sudo” command in order to access folders owned by root. It’ll ask you for the admin password once and remember it for the rest of the Terminal session. But you do have to use sudo with every command that requires root privileges, and I did not know of a way to get such privileges in Finder so all file operations were done in Terminal. Compiling the Qt library is just as one would imagine, “./configure” then “make”. Somewhere in the Makefile it creates the symbolic links to the lib file but it doesn’t copy the sym-links into a location where it can be found by other software. This was the problem I spoke of earlier, after libqt-3.1.2.dylib was built Make proceeded to build all the other software that comes with this package – tools, sample apps, etc. Obviously they couldn’t link to libqt so make errored out. It’s possible to copy the libqt-3.1.2.dylib file into /usr/lib or just make a sym-link. The install guide also says you can place the sym-link in your home directory, placement of it in /usr/lib is only if you want all users of the computer to have access to Qt. After making the link I ran make again and it proceeded to compile the rest of the software. But as of that point I was ready to test out Qt with my own code.

Play time

I wanted to use Project Builder, obviously because it’s a neat tool, but the instructions that came with Qt/Mac were pretty vague about how to actually setup a project in PB. So you guessed it, I ran into problems. It would compile everything fine, but when it came to linking and creating the app bundle, I got an error message from the linker saying “missing symbols” and the symbols in question is “vtable for TestApp.” TestApp was my QMainWindow widget, it’s also the name of the bundle, and there’s a TestApp.o as well, so I’m not sure what went wrong. I’m not qualified enough to go further with this issue, but if anyone else has some insight on this matter, please share it. So how was I going to build Qt apps? I went into the “examples” folder and browsed the sample apps to see how things were done. There was a *.pro file in each sample, and upon further research I found out these *.pro files were input for qmake. I didn’t know this previously because I’ve been using KDevelop, which hides most of the build steps for me so I only focused on writing code.

Now I have to learn the command-line way of building software. So I used the example *.pro files as a template to setup my test project. Here’s one piece of advice I’ll share that I learned from my own mistake: If you copy the sample *.pro file and just change the header and source files it defines for your build, there’s one directive at the bottom that goes like this “REQUIRES = full-config”. Leaving it in the *.pro file and passing it to qmake will lead to problems, qmake complains about the “full-config” option saying it’s not found or installed. This only happens if your working directory is not within the /usr/local/qt directory. Once I moved my project’s folder into the examples directory side by side with the other sample apps, qmake was happy. Upon removing the offending line in my *.pro file, I was able to run qmake happily from my home folder. qmake takes the input *.pro file and generates a Makefile for you. The syntax is very simple, in Terminal change to the directory where you have your source and *.pro file.

qmake -o Makefile

Afterwards, execute “make” and it begins building your app. Any time you add more source files to your project you’ll need to add them to your *.pro file, run qmake on it to get a fresh new Makefile, then build your app. I do miss the comfort of having a nice IDE to code in, but this method works and gets the job done. If you go into the “bin” directory you’ll find QT Assistant, which has all the documentation right there for you, with full documentation on how to use qmake. Download a simple template project I’ve put together.

What does it look like?

Screenshot1 – in the bin directory where you install the Qt source you’ll find “qtconfig” which lets you setup global options that affect Qt apps. Shown here is the option to change the widget theme.
Screenshot2 – Qt apps can be themed and the skin can be changed at runtime on the fly.
Screenshot3 – one of the many examples that comes with the package, this one is a collection of examples. In this shot I show off my iBook’s 3D capabilities with glxgears!


Cocoa is the native way of developing software for OSX. My own experience is that it’s very hard to unlearn C/C++ and adapt to the mentality and style of Objective-C. I’ve read comments from other developers in OSX forums who feel the same way. It’s probably best to start Objective-C with little or no prior knowledge of C/C++. Carbon apps are written in a procedural fashion but again, it comes down to how a programmer prefers to code, and this programmer doesn’t like procedural code… anymore. I have tried Metrowerks’ PowerPlant C++ framework, and I do not like it at all. It’s not as clean and elegant as Qt, and there’s no OpenGL wrapper last I checked. Qt DOES have an OpenGL widget that wraps 3D graphics functionality. I also want to point out that it’s not possible to build the Qt lib or apps that link to Qt using Metrowerks’ compiler. You must use gcc! My feelings towards Qt in general are all positive. The dual license structure makes it a great framework for people to learn and gain experience on. It also makes it possible to develop commercial applications when the time comes.

Be warned though, Trolltech’s FAQ clearly states that you may not use the Free Edition in development and then turn around and buy a commercial license at a later date and sell your software as a product. The Free Edition uses the GPL license and it is in effect from the time you begin development. Trolltech did Apple a big favor by releasing Qt/Mac. Linux developers who are already familiar with Qt will find a smooth transition into MacOSX development. Qt eliminates my concern about “is it worthwhile to develop for MacOSX?” by making it easier to write software for MacOSX and reuse knowledge and skills in a GUI library I’m already familiar with, plus source compatibility with other platforms that use Qt. Now I’m going to go make my own IDE to make it easier for me to write Qt apps in OSX! Because if I see the word “make” one more time…


  1. 2003-06-30 4:35 pm
  2. 2003-06-30 4:48 pm
  3. 2003-06-30 4:51 pm
  4. 2003-06-30 4:53 pm
  5. 2003-06-30 4:57 pm
  6. 2003-06-30 5:02 pm
  7. 2003-06-30 5:18 pm
  8. 2003-06-30 5:25 pm
  9. 2003-06-30 5:39 pm
  10. 2003-06-30 5:44 pm
  11. 2003-06-30 5:47 pm
  12. 2003-06-30 5:50 pm
  13. 2003-06-30 6:04 pm
  14. 2003-06-30 6:15 pm
  15. 2003-06-30 6:17 pm
  16. 2003-06-30 6:20 pm
  17. 2003-06-30 6:25 pm
  18. 2003-06-30 6:29 pm
  19. 2003-06-30 6:33 pm
  20. 2003-06-30 6:50 pm
  21. 2003-06-30 6:53 pm
  22. 2003-06-30 7:08 pm
  23. 2003-06-30 7:11 pm
  24. 2003-06-30 7:14 pm
  25. 2003-06-30 7:19 pm
  26. 2003-06-30 7:24 pm
  27. 2003-06-30 7:25 pm
  28. 2003-06-30 7:30 pm
  29. 2003-06-30 8:16 pm
  30. 2003-06-30 8:17 pm
  31. 2003-06-30 8:49 pm
  32. 2003-06-30 8:58 pm
  33. 2003-06-30 9:05 pm
  34. 2003-06-30 9:14 pm
  35. 2003-06-30 9:24 pm
  36. 2003-06-30 11:26 pm
  37. 2003-06-30 11:31 pm
  38. 2003-06-30 11:36 pm
  39. 2003-07-01 12:27 am
  40. 2003-07-01 12:46 am
  41. 2003-07-01 1:42 am
  42. 2003-07-01 4:49 am
  43. 2003-07-01 5:04 am
  44. 2003-07-01 1:57 pm
  45. 2003-07-01 2:31 pm
  46. 2003-07-01 3:21 pm
  47. 2003-07-01 5:41 pm
  48. 2003-07-01 7:54 pm
  49. 2003-07-01 8:50 pm
  50. 2003-07-01 9:34 pm
  51. 2003-07-01 10:17 pm
  52. 2003-07-02 12:27 am
  53. 2003-07-02 1:47 am
  54. 2003-07-02 5:29 am
  55. 2003-07-02 8:21 am
  56. 2003-07-02 8:21 am
  57. 2003-07-02 8:26 am
  58. 2003-07-02 10:04 am
  59. 2003-07-02 2:01 pm
  60. 2003-07-02 4:32 pm
  61. 2003-07-02 4:48 pm
  62. 2003-07-02 5:04 pm
  63. 2003-07-02 8:23 pm
  64. 2003-07-02 11:47 pm
  65. 2003-07-03 4:51 am
  66. 2003-07-03 2:04 pm