Qt Interface Mac: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(macOS only)
2	2
3	3		(Qt only)
4	4
5	5		## Introduction
6	6
7	7		There are two main path you can follow to start deploying your first Qt Application for Mac:
8	8
9	9		- Install compiled Interface Binary Bindings and Qt Framework Library
10	10		- Build yourself Interface Binary Bindings and Qt Framework Library (hard and may take many hours)
11	11
12	12		## Quick Install and Use Guide
13	13
14	14		Fastest way to get you ready to develop applications with Qt Framework (+ LCL Widgetset)
15	15
16	16		### Qt4 Framework Library
17	17
18	18		First you need to download the Cocoa Mac binary package of Qt4 Framework Library from [Nokia Qt download section](http://qt.nokia.com/downloads/qt-for-open-source-cpp-development-on-mac-os-x) or from a [Trolltech mirror](ftp://ftp.trolltech.com/qt/source/). The file you need is named something like qt-mac-opensource-4.7.4.dmg or with greater version.
19	19
20	20		- Now Mount the disk image and install the package that you find inside.
21	21
22	22		### Qt4 Interface Binary Bindings
23	23
24	24		Next you need to download the Interface Binary Bindings from [Jan.Van.hijfte site](http://users.telenet.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html), search for Mac: Libray Binary Intel, the file you download is named something like mac_bin-qt4pas-V2.4_Qt4.5.3.zip (don't worry about version in file name, it's indicating the lowest version required by Binaries).
25	25
26	26		- After you click on the downloaded file it will be automatically unpacked and you will see another zip inside, unzip it too and install the package you find inside.
27	27		- (Optional) Rename qt4.pas in qt45.pas and copy it inside /Developer/lazarus/lcl/interfaces/qt
28	28
29	29		### Build Lazarus IDE on Qt
30	30
31	31		Lazarus 1.2/1.3 You must rebuild libQt4Pas library according to your needs (32/64bit). Build with make (from terminal):
32	32
33	33		- 32bit (Carbon): make bigide LCL_PLATFORM=qt
34	34		- 64bit (Cocoa): make bigide OS_TARGET=darwin CPU_PLATFORM=x86_64 LCL_PLATFORM=qt
35	35
36	36		Build from Lazarus IDE:
37	37
38	38		- 32bit just set qt widgetset in ide build config dialog and rebuild.
39	39		- 64bit set qt widgetset and add -Px86_64 -Tdarwin in ide build config dialog.IMPORTANT NOTE: you must build IDE with make first (from terminal), and then you can rebuild from IDE because of bug (dunno where it is) which causes linking of lazarus against 32bit objects.
40	40
41	41		===Build Lazarus with qt-cocoa (qt binary distribution from nokia \>= 4.7.4)=== Qt binary distribution (\>=4.7.4) is 64bit (cocoa only), so we need 64bit Qt4Pas and 64bit 2.6.0 compiler
42	42
43	43		- Download and install fpc-2.6.0 (with 2.4.4 64bit you can compile lazarus etc but it will crash imediatelly).I've used "svn co <http://svn.freepascal.org/svn/fpc/tags/release_2_6_0> fpc260" , then "fpcmake -Tall" , "make all", "sudo make install", "sudo make CPU_TARGET=x86_64 make install" (of course you need fpc-2.4.4 to build 2.6.0, you can download dmgs from lazarus daily snapshots.
44	44		- Download qt-4.7.4 from nokia site (DO NOT DOWNLOAD 4.8.0 SINCE IT'S WRONGLY PACKAGED atm - won't work (missing symbols in QWebKit) <https://bugreports.qt.nokia.com/browse/QTBUG-23157> )
45	45		- Install qt
46	46		- Download qt bindings source (Qt4Pas).
47	47		- Open Qt4Pas.pro and comment CXXFLAGS += -mstackrealign (since it will be error with 64bit build on mac).
48	48		- Build and install bindings as in readme.
49	49		- dload lazarus trunk.
50	50
51	51		Build from terminal (short way)
52	52
53	53		- make bigide CPU_TARGET=x86_64 LCL_PLATFORM=qt OPT="-k'-framework' -k'ApplicationServices'" (don't forget to change default compiler in Tools-\>Options-\>Compiler path)
54	54
55	55		Build carbon from terminal, then ide from ide
56	56
57	57		- build it for carbon (32bit), startlazarus, go to Tools-\>Options, change cpu from /usr/local/bin/fpc to /usr/local/bin/ppcx64 in Compiler path (also fix source path to 2.6.0 if it isn't already fixed).
58	58		- Tools-\>Configure Build Lazarus-\> choose LCL widget type qt, in options write -k-framework -kApplicationServices (yes, without any quotes)
59	59		- Build lazarus
60	60
61	61		Spotted problems
62	62
63	63		- Qt-cocoa have problems with mouseGrabber (possible it's fixed in 4.8.0)
64	64		- Cannot build pure cocoa widget set ATSUXXXX symbols are missing (probably need to pass more frameworks to linker)
65	65
66	66		Build environment
67	67
68	68		- 10.6.8 (Snow Leopard)
69	69		- XCode 3.(Don't know - but it's free one)
70	70
71	71		### Build your first Qt Application
72	72
73	73		- Note: Latest Lazarus IDE creates [[Application Bundle\|Application Bundles]] by himself when you create a new project, so you don't need to worry about this (while you leave the Create Application Bundle check box inside Project -\> Project Options -\> Application tab to it's default enabled state.
74	74
75	75		1. Create a new project or use the default one that Lazarus IDE creates on first launch.
76	76		2. Add some buttons and edit boxes to your form.
77	77		3. Inside Project -\> Project Options -\> Compile Options -\> Build modes click on empty macro line and choose LCLWidgetType, in relative macro value choose qt and click Ok.
78	78		4. Now click green Run arrow and congratulate with yourself for building your first Qt Application.
79	79
80	80		------------------------------------------------------------------------
81	81
82	82		## Outdated Build Guide
83	83
84	84		Shebuka 17:03, 8 September 2011 (CEST) At this time, this part of guide can't be followed, because all shell script mentioned here to build Interface and Libraries are not present in [Mac library sources](http://users.pandora.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html).
85	85
86	86		Sections 2, 3, and 4 only need to be done if you are creating the Interface library, and Interface framework yourself. If you have installed the interface framework using [Mac Library Binary (intel)](http://users.pandora.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html), you can start with section 5 and begin compiling the demo programs.
87	87
88	88		Notes on terminology:
89	89
90	90		These instructions generally use the term "Qt libraries" to describe the QtCore and QtGui libraries that are created in section 2. The term "interface library" is used to describe the Qt4Intf library created in section 3 that interfaces between Free Pascal and the Qt libraries. The "interface framework" is an macOS-specific folder created in section 4 that contains both the Qt libraries and interface library and can be linked against when compiling with Free Pascal.
91	91
92	92		If you're not familiar with macOS terms such as "framework" and "app bundle", refer to Apple's extensive [online documentation](https://developer.apple.com/documentation/).
93	93
94	94		*Important!* To run any of the scripts mentioned in sections 3-6, you may need to change its permission so that macOS will allow it to be executed:
95	95
96	96		chmod +x script_name.sh
97	97
98	98		### Install the Qt Library Frameworks
99	99
100	100		- Download and install Qt4 from Trolltech/Nokia: [1](http:/ftp://ftp.trolltech.com/qt/source/). The file will be named something like qt-mac-opensource-4.5.X.dmg.
101	101		- Several Qt frameworks will be installed in /Library/Frameworks. QtCore.framework and QtGui.framework are used.
102	102
103	103		### Creating the Qt interface library
104	104
105	105		A script file for doing this is included with [Mac library source](http://users.pandora.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html). The downloaded file will be named like mac_qt4pas-V1.XX_Qt4.4.X.zip Download and double-click this file to create folder qt4pas-V1.XX_Qt4.4.X.zip. Move this folder to your home folder and change to it (cd). Run the script as follows:
106	106
107	107		./compile_lib_mac.sh
108	108
109	109		This script will use the GCC g++ (installation of macOS DevSDK (Xcode) is required) compiler to compile qtpas.cpp and create Qt4Intf, the Qt interface library. If the script can't find the Qt4 library frameworks, it will output an error message. The script does not check the exact Qt version, use the appropriate Qt (Qt4.3.X cannot be mixed with Qt 4.4.X)
110	110
111	111		### Creating the Qt interface framework
112	112
113	113		A script file for doing this is included with mac_qt4pas-1.xx.zip. Run the script as follows:
114	114
115	115		sudo ./create_framework_mac.sh
116	116
117	117		This creates the Qt4Intf.framework folder under /Library/Frameworks. Note that sudo is required because of the need of write access in the /Library/Frameworks folder.
118	118
119	119		If the script can't find the Qt4Intf library it needs, it will output an error message. you need to compile it first (see step above)
120	120
121	121		### Compiling the non-Lazarus demo programs with Free Pascal
122	122
123	123		The Pascal source for several demo programs is included in file [mac_demos-1.xx.zip](http://users.pandora.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html). Download and double-click this file to create folder demos-1.xx. Move this folder to your home folder (/Users/login) and change to it (cd).
124	124
125	125		To compile one of the demo programs:
126	126
127	127		cd somedemo
128	128		../compile_exe_fr_mac.sh somedemo
129	129
130	130		This will compile the demo program with Free Pascal, creating an executable file with the same name.
131	131
132	132		*Tip:* The compile script uses the compiler option -Fu..(find units in parent directory) to only need a single copy for all demoes of the rather large Qt4.pas file.
133	133
134	134		Note that Lazarus is not required to compile these demo programs.
135	135
136	136		### Creating a demo program application bundle
137	137
138	138		To create a double-clickable application on macOS, you need to create an app bundle. An app bundle is a folder with an .app extension in its name that looks like a file to the user. A script file is included for doing this:
139	139
140	140		../create_app_mac.sh somedemo
141	141
142	142		This creates the somedemo.app folder, as well as several folders and files inside it.
143	143
144	144		Note that this script does not copy the executable file into the app bundle the way you normally would when you're ready to distribute an app bundle. Instead, it creates a symbolic link inside the folder that points to the executable in the somedemo folder. This approach allows you to edit and compile a program as many times as necessary without needing to copy the executable file into the app bundle folder after each compile in order to run it.
145	145
146	146		In Finder, double-click the somedemo application (not the executable file) to launch it. You can also drag and drop the somedemo application onto the dock and launch it from there.
147	147
148	148		### Creating a Qt based Lazarus
149	149
150	150		#### Starting purely from source
151	151
152	152		Note: The X11 package does not have to be installed at all.
153	153
154	154		- Checkout svn source
155	155
156	156		in a terminal do
157	157
158		-	~~`svn co `[`http://svn.freepascal.org/svn/lazarus/trunk`](http://svn.freepascal.org/svn/lazarus/trunk)` lazarus`~~
	158	+	```text
	159	+	svn co http://svn.freepascal.org/svn/lazarus/trunk lazarus
	160	+	```
159	161
160	162		- Compile lazarus using installed Qt4Intf framework
161	163		- adapt USE_QT_45 to the used Qt version
162	164		- since svn \>= 21913, Qt 4.5 is default, no need to define any USE_XX_YY when using Qt 4.5
163	165
164		-	~~`cd lazarus`\~~
165		-	~~`make clean all LCL_PLATFORM=qt OPT="-dUSE_QT_45 -k'-framework' -k'Qt4Intf' -k'-lobjc' -k'-framework' -k'Foundation'"`~~
	166	+	```text
	167	+	cd lazarus
	168	+	make clean all LCL_PLATFORM=qt OPT="-dUSE_QT_45 -k'-framework' -k'Qt4Intf' -k'-lobjc' -k'-framework' -k'Foundation'"
	169	+	```
166	170
167	171		- run lazarus :-)
168	172
169		-	~~`./startlazarus`~~
	173	+	```text
	174	+	./startlazarus
	175	+	```
170	176
171	177		#### Starting from a Gtk based Lazarus
172	178
173	179		Currently Lazarus is only available for the X11-based GTK widgetset. The compiled LCL units included with Lazarus are only available for the GTK widgetset as well. The LCL units are also installed read-only, so the easiest way of compiling them for the Qt widgetset is simply to copy the LCL source to your home folder and rebuild it there. Here are the steps:
174	180
175	181		- Copy the "lazarus" folder from /usr/local/share to your home folder (/Users/login).
176	182
177	183		*Tip:* How do you get to the Lazarus folder? In Finder, choose Go \\| Go to Folder and enter /usr, then navigate to /usr/local/share.
178	184
179	185		*Tip:* You can also use Subversion (SVN) to download the Lazarus source to a folder in your home folder (or someplace where you have write access to it).
180	186
181	187		*Tip:* For the purposes of these examples, you really only need to copy the Lazarus "lcl" folder, but you'll need to ignore the warnings that Lazarus gives you later on.
182	188
183	189		- Make sure the Qt widgetset is using an up-to-date version of qt4.pas. Compare the version of qt4.pas file used in section 5 above with /Users/login/Lazarus/lcl/interfaces/qt/qt4.pas. The version should be indicated in a comment at the top of qt4.pas. If necessary, install a more recent version of Lazarus.
184	190
185	191		- Start Lazarus by opening an X11 window and entering:
186	192
187	193		cd /usr/local/share/lazarus
188	194		./lazarus
189	195
190	196		- In Lazarus, choose Tools -\> Options -\> Environment. On the Files tab, change the Lazarus directory from /usr/local/share/lazarus to
191	197
192	198		/Users/login/Lazarus
193	199
194	200		If you only copied the "lcl" folder, you'll get a warning when you click OK. Click Ignore to ignore the warning.
195	201
196	202		- In Lazarus, choose Tools \\| Configure "Build Lazarus". Set Build LCL to "Build"; set all others to "None". Also click "qt" under LCL interface.
197	203
198	204		- Click the Build button.
199	205
200	206		- When Free Pascal is done compiling the LCL, check that you have newly created .ppu and .o files in /Users/login/Lazarus/lcl/units/powerpc-darwin/qt.
201	207
202	208		- Choose Tools \\| Configure, restore the LCL interface setting to "gtk", then click "Save settings".
203	209
204	210		### Creating an LCL app that uses the Qt widgetset
205	211
206	212		- Create a new project in Lazarus. When you started Lazarus, it created a new project -- you can use this.
207	213
208	214		- In Lazarus, choose Project \\| Compiler Options. On the Paths tab, select "qt" under LCL Widget Type.
209	215
210	216		- On the Linking tab, select Pass Options To The Linker and enter
211	217
212	218		-framework Qt4Intf -lobjc -framework Foundation
213	219
214	220		and click OK.
215	221
216	222		- Add one or more controls to your project's main form. Since the Qt widgetset is a work in progress, consult [[Roadmap\|Roadmap#Widgetset_dependent_components]] to see which controls are working.
217	223
218	224		In the meantime qt widgetset becomes more mature, so you can see [Lazarus Qt IDE under macOS](http://wiki.lazarus.freepascal.org/Image:macosxqt.png)
219	225
220	226		- Save the project to a folder in your home folder (/Users/login).
221	227
222	228		- In Lazarus, choose Run \\| Build to compile the project.
223	229
224	230		*Tip:* You can also compile your project from a script:
225	231
226	232		qtunits=~/lazarus/lcl/units/powerpc-darwin
227	233		/usr/local/bin/fpc -dLCL -WG -Sd -gl -O1 -Cirot -k'-framework' -k'Qt4Intf' -k'-lobjc' -Fu$qtunits -Fu$qtunits/qt myproj.lpr
228	234
229	235		You can change most of the switches as needed, but be sure to leave the -k switches alone. If necessary, change the first line to the path to the LCL units you created in the previous section.
230	236
231	237		- Before running the app, make sure you've created an app bundle for it. You can copy the create_app_mac.sh script from section 6 to your project's folder and run it to create an app bundle for your compiled project.
232	238
233	239		- To run the app, double-click the application (not the executable file) in Finder or drag it to the dock and launch it from there.
234	240
235	241		- Before writing mac apps read [macOS Human Interface guidelines](https://developer.apple.com/design/human-interface-guidelines/macos/overview/themes/).
236	242
237	243		------------------------------------------------------------------------
238	244
239	245		## Distributing an app that uses the Qt Interface Framework
240	246
241	247		- The Lazarus IDE creates a symbolic link inside the application bundle to the actual executable file. To copy the executable file into the application bundle in order to distribute it along with the application bundle, do this:
242	248
243	249		cd /path/to/your/application/bundle
244	250		rm MyApp.app/Contents/MacOS/MyApp
245	251		cp -p MyApp MyApp.app/Contents/MacOS/MyApp
246	252
247	253		You should substitute the name of your application for "MyApp" above.
248	254
249	255		- Consult [[Deploying Your Application\|Deploying Your Application#An Application Bundle]] for help with creating a distributable disk image file (.dmg extension) from your application bundle folder. Ignore the discussion of X11 and GTK since your app does not require them!
250	256
251	257		- Your application will depend on the Qt4 Framework Library and on the Qt4 Interface Binary Bindings. You can put these files inside your application bundle like you do with .dylib following [[macOS Programming Tips\|macOS Programming Tips#Using a library in a Mac application]].
252	258
253	259		- Read [Deploying an Application on macOS](http://qt-project.org/doc/qt-4.8/deployment-mac.html) about adding the Qt framework to your application bundle. Very handy for that purpose is the tool macdeployqt.
254	260
255	261		## Uninstalling the Qt4 Interface and Qt4 Framework
256	262
257	263		- If you need to remove the Qt4 Interface from your computer, simply drag the Qt4Pas.framework folder from /Library/Frameworks to the trash. Finder will prompt you for your password before allowing this.
258	264
259	265		- If you need to remove the Qt4 Framework from your computer, simply drag the Qt3Support.framework and all QtXxxx.framework folders (like QtCore.framework, QtGui.framework, QtWebKit.framework ecc.) from /Library/Frameworks to the trash. Finder will prompt you for your password before allowing this.
260	266
261	267		- (Optional) You can also drag Qt4 Free Pascal Interface.pkg (if present) from /Library/Receipts to the trash.
262	268
263	269		---
264	270		From the Free Pascal wiki, page "Qt Interface Mac", as it stood on 2020-01-27 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history