Application Bundle: what changed

Revision 4 to 5. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Overview
2	2
3	3		An application bundle is a directory with the extension ".app" on macOS systems. It contains the application executable, resource files, library files (if any), help files and information about the application and is necessary for the correct execution of applications. The Mac Finder treats this .app directory as the application file and by default does not show any of its sub-directories.
4	4
5	5		From within Lazarus it is used for the [[Carbon Interface\|Carbon]] and [[Cocoa Interface\|Cocoa]] interfaces, but one can also build applications with other interfaces (eg Gtk or Qt) by using scripts.
6	6
7	7		You can learn more about application bundles in the Apple Bundle Programming Guide.
8	8
9	9		Application (bundle) settings are located in the property list file: [[macOS property list files\|Info.plist]] located in the `bundle.app/Contents/` directory.
10	10
11	11		The PkgInfo file is an alternative way to specify the type and creator codes of your application or bundle. This file is not required, but can improve performance for code that accesses this information. Regardless of whether you provide this file, you should always include type and creator information in your information property list file using the CFBundlePackageType and CFBundleSignature keys, respectively. The contents of the PkgInfo file are the 4-byte package type followed by the 4-byte signature of your application. Thus, for the TextEdit application, whose type is 'APPL' and whose signature is 'ttxt', the file would contain the ASCII string “APPLttxt”.
12	12
13	13		To access the application bundle contents in Finder, you need to right click (ctrl-left click) on a bundle and select Show Package Contents
14	14
15	15		![](/wiki-images/1/12/Openbundle.png)
16	16
17	17		![](/wiki-images/8/81/Infoplist.png)
18	18
19	19		## Application bundle layout
20	20
21	21		The basic structure of a Mac application bundle:
22	22
23		-	~~`MyApp.app/`\~~
24		-	~~` Contents/`\~~
25		-	~~` Info.plist`\~~
26		-	~~` MacOS/`\~~
27		-	~~` PkgInfo`\~~
28		-	~~` Resources/`~~
	23	+	```
	24	+	MyApp.app/
	25	+	Contents/
	26	+	Info.plist
	27	+	MacOS/
	28	+	PkgInfo
	29	+	Resources/
	30	+	```
29	31
30	32		\| Sub-Directory of the Contents directory \| Usage description \|
31	33		\|----\|----\|
32	34		\| MacOS \| (Required) Contains the application’s standalone executable code. Typically, this directory contains only one binary file with your application’s main entry point and statically linked code. However, you may put other standalone executables (such as command-line tools) in this directory as well. \|
33	35		\| Resources \| Contains all of the application’s resource files. The contents of this directory are further organized to distinguish between localized and nonlocalized resources. For more information about the structure of this directory, see [[Add an Apple Help Book to your macOS app\|Adding a Help Book - Bundle layouts]]. \|
34	36		\| Frameworks \| Contains any private shared libraries and frameworks used by the executable. The frameworks in this directory are revision-locked to the application and cannot be superseded by any other, even newer, versions that may be available to the operating system. In other words, the frameworks included in this directory take precedence over any other similarly named frameworks found in other parts of the operating system. For information on how to add shared libraries to your application bundle, see [[macOS Dynamic Libraries]]. \|
35	37		\| PlugIns \| Contains loadable bundles that extend the basic features of your application. You use this directory to include code modules that must be loaded into your application’s process space in order to be used. You would not use this directory to store standalone executables. \|
36	38		\| SharedSupport \| Contains additional non-critical resources that do not impact the ability of the application to run. You might use this directory to include things like document templates, clip art, and tutorials that your application expects to be present but that do not affect the ability of your application to run. \|
37	39
38	40		## Creating the Application Bundle
39	41
40	42		### Using Lazarus
41	43
42	44		Open a project in the Lazarus IDE and go to Project -\> Project Options -\> Application tab and push the [[IDE Window: Project Options\|Create Application Bundle]] button. The resulting Application Bundle will contain a symbolic link to the real executable.
43	45
44	46		> Note: You must remove the symbolic link and copy the real executable "project1" into the `project1.app/Contents/MacOS/` directory to distribute the application and use it on another computer.
45	47
46	48		### Using the Lazarus command-line tool
47	49
48	50		Open `/Applications/Lazarus/components/macfiles/examples/createmacapplication.lpi` in the Lazarus IDE. Compile.
49	51
50	52		Open a Terminal of your choice and type:
51	53
52	54		``` bash
53	55		cd project1/
54	56		/Applications/Lazarus/components/macfiles/examples/createmacapplication project1
55	57		ln -s ../../../project1 project1.app/Contents/MacOS/project1
56	58		```
57	59
58	60		### Using a shell script
59	61
60	62		You can adapt the following shell script to create a customized application bundle for your application. It allows the creation of either a debug or a release bundle.
61	63
62	64		- In the debug bundle, a link to the executable is placed, allowing for debugging using the Lazarus IDE,
63	65		- In the release bundle, the executable is copied so the application bundle as a whole can be used stand-alone/copied to other locations.
64	66
65	67		``` bash
66	68		#!/bin/sh
67	69		# Force Bourne shell in case tcsh is default.
68	70		#
69	71
70	72		#
71	73		# Reads the bundle type
72	74		#
73	75
74	76		echo "========================================================"
75	77		echo " Bundle creation script"
76	78		echo "========================================================"
77	79		echo ""
78	80		echo " Please select which kind of bundle you would like to build:"
79	81		echo ""
80	82		echo " 1 > Debug bundle"
81	83		echo " 2 > Release bundle"
82	84		echo " 0 > Exit"
83	85
84	86		read command
85	87
86	88		case $command in
87	89
88	90		1) ;;
89	91
90	92		2) ;;
91	93
92	94		0) exit 0;;
93	95
94	96		*) echo "Invalid command"
95	97		exit 0;;
96	98
97	99		esac
98	100
99	101		#
100	102		# Creates the bundle
101	103		#
102	104
103	105		appname=Magnifier
104	106		appfolder=$appname.app
105	107		macosfolder=$appfolder/Contents/MacOS
106	108		plistfile=$appfolder/Contents/Info.plist
107	109		appfile=magnifier
108	110
109	111		PkgInfoContents="APPL????"
110	112
111	113		#
112	114		if ! [ -e $appfile ]
113	115		then
114	116		echo "$appfile does not exist"
115	117		elif [ -e $appfolder ]
116	118		then
117	119		echo "$appfolder already exists"
118	120		else
119	121		echo "Creating $appfolder..."
120	122		mkdir $appfolder
121	123		mkdir $appfolder/Contents
122	124		mkdir $appfolder/Contents/MacOS
123	125		mkdir $appfolder/Contents/Frameworks # optional, for including libraries or frameworks
124	126		mkdir $appfolder/Contents/Resources
125	127
126	128		#
127	129		# For a debug bundle,
128	130		# Instead of copying executable into .app folder after each compile,
129	131		# simply create a symbolic link to executable.
130	132		#
131	133		if [ $command = 1 ]; then
132	134		ln -s ../../../$appname $macosfolder/$appname
133	135		else
134	136		cp $appname $macosfolder/$appname
135	137		fi
136	138
137	139		# Copy the resource files to the correct place
138	140		cp *.bmp $appfolder/Contents/Resources
139	141		cp icon3.ico $appfolder/Contents/Resources
140	142		cp icon3.png $appfolder/Contents/Resources
141	143		cp macicon.icns $appfolder/Contents/Resources
142	144		cp docs/. $appfolder/Contents/Resources
143	145		#
144	146		# Create PkgInfo file.
145	147		echo $PkgInfoContents >$appfolder/Contents/PkgInfo
146	148		#
147	149		# Create information property list file (Info.plist).
148	150		echo '<?xml version="1.0" encoding="UTF-8"?>' >$plistfile
149	151		echo '<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >>$plistfile
150	152		echo '<plist version="1.0">' >>$plistfile
151	153		echo '<dict>' >>$plistfile
152	154		echo ' <key>CFBundleDevelopmentRegion</key>' >>$plistfile
153	155		echo ' <string>English</string>' >>$plistfile
154	156		echo ' <key>CFBundleExecutable</key>' >>$plistfile
155	157		echo ' <string>'$appname'</string>' >>$plistfile
156	158		echo ' <key>CFBundleIconFile</key>' >>$plistfile
157	159		echo ' <string>macicon.icns</string>' >>$plistfile
158	160		echo ' <key>CFBundleIdentifier</key>' >>$plistfile
159	161		echo ' <string>org.magnifier.magnifier</string>' >>$plistfile
160	162		echo ' <key>CFBundleInfoDictionaryVersion</key>' >>$plistfile
161	163		echo ' <string>6.0</string>' >>$plistfile
162	164		echo ' <key>CFBundlePackageType</key>' >>$plistfile
163	165		echo ' <string>APPL</string>' >>$plistfile
164	166		echo ' <key>CFBundleSignature</key>' >>$plistfile
165	167		echo ' <string>MAG#</string>' >>$plistfile
166	168		echo ' <key>CFBundleVersion</key>' >>$plistfile
167	169		echo ' <string>1.0</string>' >>$plistfile
168	170		echo '</dict>' >>$plistfile
169	171		echo '</plist>' >>$plistfile
170	172		fi
171	173		```
172	174
173	175		## Executing an application via the Application Bundle
174	176
175	177		You can start the application from the Lazarus IDE, by clicking on its Finder icon or in the native macOS Terminal.app by typing:
176	178
177	179		``` bash
178	180		open project1.app
179	181		```
180	182
181	183		or
182	184
183	185		``` bash
184	186		./project1.app/Contents/MacOS/project1
185	187		```
186	188
187	189		## See also
188	190
189	191		- [[Add an Apple Help Book to your macOS app]]
190	192		- [[Deploying Your Application\|Deploying your macOS application]]
191	193		- [[Hiding a macOS app from the Dock]]
192	194		- [[macOS property list files]]
193	195
194	196		## External links
195	197
196	198		- [Apple: NSBundle class](https://developer.apple.com/documentation/foundation/nsbundle)
197	199		- [Apple: Bundle Resources](https://developer.apple.com/documentation/bundleresources/)
198	200		- [Apple: CFBundle](https://developer.apple.com/documentation/corefoundation/cfbundle)
199	201		- [Apple: Bundle Configuration](https://developer.apple.com/documentation/bundleresources/information_property_list/bundle_configuration)
200	202		- [Apple: Resource Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Introduction/Introduction.html)
201	203		- [Apple: Bundle Programming Guide](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html)
202	204
203	205		---
204	206		From the Free Pascal wiki, page "Application Bundle", as it stood on 2022-03-13 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