Sign in Join
Wiki copytemporary

Application Bundle: what changed

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

OldNewLine
1-## Overview
1+[![macOSlogo.png](/wiki-images/1/15/macOSlogo.png)](</File:macOSlogo.png>)
22
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.
3+This article applies to [macOS](</Category:macOS> "Category:macOS") only.
44
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.
5+See also: [[Multiplatform Programming Guide]]
66
7-You can learn more about application bundles in the Apple Bundle Programming Guide.
7+
8+****
89
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+## Contents
1011
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+ * 1 Overview
13+ * 2 Application bundle layout
14+ * 3 Creating the Application Bundle
15+ * 3.1 Using Lazarus
16+ * 3.2 Using the Lazarus command-line tool
17+ * 3.3 Using a shell script
18+ * 4 Executing an application via the Application Bundle
19+ * 5 See also
20+ * 6 External links
1221
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*
22+## Overview
1423
15-![](/wiki-images/1/12/Openbundle.png)
24+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.
1625
17-![](/wiki-images/8/81/Infoplist.png)
26+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.
1827
19-## Application bundle layout
28+You can learn more about application bundles in the Apple Bundle Programming Guide.
2029
21-The basic structure of a Mac application bundle:
30+Application (bundle) settings are located in the property list file: [[macOS property list files|Info.plist]] located in the `bundle.app/Contents/` directory.
2231
23-`MyApp.app/`\
24-`   Contents/`\
25-`      Info.plist`\
26-`      MacOS/`\
27-`      PkgInfo`\
28-`      Resources/`
32+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”.
2933
30-| Sub-Directory of the Contents directory | Usage description |
31-|----|----|
32-| 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-| 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-| 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-| 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-| 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. |
34+To access the application bundle contents in Finder, you need to right click (ctrl-left click) on a bundle and select _Show Package Contents_
3735
36+[![openbundle.png](/wiki-images/d/d2/openbundle.png)](</File:openbundle.png>)
37+
38+[![infoplist.png](/wiki-images/8/80/infoplist.png)](</File:infoplist.png>)
39+
40+## Application bundle layout
41+
42+The basic structure of a Mac application bundle:
43+```
44+MyApp.app/
45+ Contents/
46+ Info.plist
47+ MacOS/
48+ PkgInfo
49+ Resources/
50+```
51+
52+Sub-Directory of the Contents directory | Usage description
53+---|---
54+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.
55+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]].
56+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]].
57+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.
58+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.
59+
3860## Creating the Application Bundle
3961
4062### Using Lazarus
4163
42-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.
64+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.
4365
44-> **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.
66+[![Note-icon.png](/wiki-images/b/be/Note-icon.png)](</File:Note-icon.png>)
4567
46-### Using the Lazarus command-line tool
68+**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.
4769
48-Open `/Applications/Lazarus/components/macfiles/examples/createmacapplication.lpi` in the Lazarus IDE. Compile.
70+### Using the Lazarus command-line tool
4971
50-Open a Terminal of your choice and type:
72+Open `/Applications/Lazarus/components/macfiles/examples/createmacapplication.lpi` in the Lazarus IDE. Compile.
5173
52-``` bash
74+Open a Terminal of your choice and type:
75+```
5376cd project1/
54-/Applications/Lazarus/components/macfiles/examples/createmacapplication project1
55-ln -s ../../../project1 project1.app/Contents/MacOS/project1
77+ /Applications/Lazarus/components/macfiles/examples/createmacapplication project1
78+ ln -s ../../../project1 project1.app/Contents/MacOS/project1
5679```
5780
5881### Using a shell script
5982
60-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.
83+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.
6184
62-- In the debug bundle, a link to the executable is placed, allowing for debugging using the Lazarus IDE,
63-- In the release bundle, the executable is copied so the application bundle as a whole can be used stand-alone/copied to other locations.
85+ * In the debug bundle, a link to the executable is placed, allowing for debugging using the Lazarus IDE,
86+ * In the release bundle, the executable is copied so the application bundle as a whole can be used stand-alone/copied to other locations.
6487
65-``` bash
88+```
6689#!/bin/sh
67-# Force Bourne shell in case tcsh is default.
68-#
69-
70-#
71-# Reads the bundle type
72-#
73-
74-echo "========================================================"
75-echo " Bundle creation script"
76-echo "========================================================"
77-echo ""
78-echo " Please select which kind of bundle you would like to build:"
79-echo ""
80-echo " 1 > Debug bundle"
81-echo " 2 > Release bundle"
82-echo " 0 > Exit"
83-
84-read command
85-
86-case $command in
87-
88- 1) ;;
89-
90- 2) ;;
91-
92- 0) exit 0;;
93-
94- *) echo "Invalid command"
95- exit 0;;
96-
97-esac
98-
99-#
100-# Creates the bundle
101-#
102-
103-appname=Magnifier
104-appfolder=$appname.app
105-macosfolder=$appfolder/Contents/MacOS
106-plistfile=$appfolder/Contents/Info.plist
107-appfile=magnifier
108-
109-PkgInfoContents="APPL????"
110-
111-#
112-if ! [ -e $appfile ]
113-then
114- echo "$appfile does not exist"
115-elif [ -e $appfolder ]
116-then
117- echo "$appfolder already exists"
118-else
119- echo "Creating $appfolder..."
120- mkdir $appfolder
121- mkdir $appfolder/Contents
122- mkdir $appfolder/Contents/MacOS
123- mkdir $appfolder/Contents/Frameworks # optional, for including libraries or frameworks
124- mkdir $appfolder/Contents/Resources
125-
126-#
127-# For a debug bundle,
128-# Instead of copying executable into .app folder after each compile,
129-# simply create a symbolic link to executable.
130-#
131-if [ $command = 1 ]; then
132- ln -s ../../../$appname $macosfolder/$appname
133-else
134- cp $appname $macosfolder/$appname
135-fi
136-
137-# Copy the resource files to the correct place
138- cp *.bmp $appfolder/Contents/Resources
139- cp icon3.ico $appfolder/Contents/Resources
140- cp icon3.png $appfolder/Contents/Resources
141- cp macicon.icns $appfolder/Contents/Resources
142- cp docs/*.* $appfolder/Contents/Resources
143-#
144-# Create PkgInfo file.
145- echo $PkgInfoContents >$appfolder/Contents/PkgInfo
146-#
147-# Create information property list file (Info.plist).
148- echo '<?xml version="1.0" encoding="UTF-8"?>' >$plistfile
149- echo '<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >>$plistfile
150- echo '<plist version="1.0">' >>$plistfile
151- echo '<dict>' >>$plistfile
152- echo ' <key>CFBundleDevelopmentRegion</key>' >>$plistfile
153- echo ' <string>English</string>' >>$plistfile
154- echo ' <key>CFBundleExecutable</key>' >>$plistfile
155- echo ' <string>'$appname'</string>' >>$plistfile
156- echo ' <key>CFBundleIconFile</key>' >>$plistfile
157- echo ' <string>macicon.icns</string>' >>$plistfile
158- echo ' <key>CFBundleIdentifier</key>' >>$plistfile
159- echo ' <string>org.magnifier.magnifier</string>' >>$plistfile
160- echo ' <key>CFBundleInfoDictionaryVersion</key>' >>$plistfile
161- echo ' <string>6.0</string>' >>$plistfile
162- echo ' <key>CFBundlePackageType</key>' >>$plistfile
163- echo ' <string>APPL</string>' >>$plistfile
164- echo ' <key>CFBundleSignature</key>' >>$plistfile
165- echo ' <string>MAG#</string>' >>$plistfile
166- echo ' <key>CFBundleVersion</key>' >>$plistfile
167- echo ' <string>1.0</string>' >>$plistfile
168- echo '</dict>' >>$plistfile
169- echo '</plist>' >>$plistfile
170-fi
90+ # Force Bourne shell in case tcsh is default.
91+ #
92+
93+ #
94+ # Reads the bundle type
95+ #
96+
97+ echo "========================================================"
98+ echo " Bundle creation script"
99+ echo "========================================================"
100+ echo ""
101+ echo " Please select which kind of bundle you would like to build:"
102+ echo ""
103+ echo " 1 > Debug bundle"
104+ echo " 2 > Release bundle"
105+ echo " 0 > Exit"
106+
107+ read command
108+
109+ case $command in
110+
111+ 1) ;;
112+
113+ 2) ;;
114+
115+ 0) exit 0;;
116+
117+ *) echo "Invalid command"
118+ exit 0;;
119+
120+ esac
121+
122+ #
123+ # Creates the bundle
124+ #
125+
126+ appname=Magnifier
127+ appfolder=$appname.app
128+ macosfolder=$appfolder/Contents/MacOS
129+ plistfile=$appfolder/Contents/Info.plist
130+ appfile=magnifier
131+
132+ PkgInfoContents="APPL????"
133+
134+ #
135+ if ! [ -e $appfile ]
136+ then
137+ echo "$appfile does not exist"
138+ elif [ -e $appfolder ]
139+ then
140+ echo "$appfolder already exists"
141+ else
142+ echo "Creating $appfolder..."
143+ mkdir $appfolder
144+ mkdir $appfolder/Contents
145+ mkdir $appfolder/Contents/MacOS
146+ mkdir $appfolder/Contents/Frameworks # optional, for including libraries or frameworks
147+ mkdir $appfolder/Contents/Resources
148+
149+ #
150+ # For a debug bundle,
151+ # Instead of copying executable into .app folder after each compile,
152+ # simply create a symbolic link to executable.
153+ #
154+ if [ $command = 1 ]; then
155+ ln -s ../../../$appname $macosfolder/$appname
156+ else
157+ cp $appname $macosfolder/$appname
158+ fi
159+
160+ # Copy the resource files to the correct place
161+ cp *.bmp $appfolder/Contents/Resources
162+ cp icon3.ico $appfolder/Contents/Resources
163+ cp icon3.png $appfolder/Contents/Resources
164+ cp macicon.icns $appfolder/Contents/Resources
165+ cp docs/*.* $appfolder/Contents/Resources
166+ #
167+ # Create PkgInfo file.
168+ echo $PkgInfoContents >$appfolder/Contents/PkgInfo
169+ #
170+ # Create information property list file (Info.plist).
171+ echo '<?xml version="1.0" encoding="UTF-8"?>' >$plistfile
172+ echo '<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >>$plistfile
173+ echo '<plist version="1.0">' >>$plistfile
174+ echo '<dict>' >>$plistfile
175+ echo ' <key>CFBundleDevelopmentRegion</key>' >>$plistfile
176+ echo ' <string>English</string>' >>$plistfile
177+ echo ' <key>CFBundleExecutable</key>' >>$plistfile
178+ echo ' <string>'$appname'</string>' >>$plistfile
179+ echo ' <key>CFBundleIconFile</key>' >>$plistfile
180+ echo ' <string>macicon.icns</string>' >>$plistfile
181+ echo ' <key>CFBundleIdentifier</key>' >>$plistfile
182+ echo ' <string>org.magnifier.magnifier</string>' >>$plistfile
183+ echo ' <key>CFBundleInfoDictionaryVersion</key>' >>$plistfile
184+ echo ' <string>6.0</string>' >>$plistfile
185+ echo ' <key>CFBundlePackageType</key>' >>$plistfile
186+ echo ' <string>APPL</string>' >>$plistfile
187+ echo ' <key>CFBundleSignature</key>' >>$plistfile
188+ echo ' <string>MAG#</string>' >>$plistfile
189+ echo ' <key>CFBundleVersion</key>' >>$plistfile
190+ echo ' <string>1.0</string>' >>$plistfile
191+ echo '</dict>' >>$plistfile
192+ echo '</plist>' >>$plistfile
193+ fi
171194```
172195
173196## Executing an application via the Application Bundle
174197
175-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-
177-``` bash
198+You can start the application from the Lazarus IDE, by clicking on its Finder icon or in the native macOS Terminal.app by typing:
199+```
178200open project1.app
179201```
180202
181-or
182-
183-``` bash
203+or
204+```
184205./project1.app/Contents/MacOS/project1
185206```
186207
187208## See also
188209
189-- [[Add an Apple Help Book to your macOS app]]
190-- [[Deploying Your Application|Deploying your macOS application]]
191-- [[Hiding a macOS app from the Dock]]
192-- [[macOS property list files]]
210+ * [[Add an Apple Help Book to your macOS app]]
211+ * [[Deploying Your Application|Deploying your macOS application]]
212+ * [[Hiding a macOS app from the Dock]]
213+ * [[macOS property list files]]
193214
194215## External links
195216
196-- [Apple: NSBundle class](https://developer.apple.com/documentation/foundation/nsbundle)
197-- [Apple: Bundle Resources](https://developer.apple.com/documentation/bundleresources/)
198-- [Apple: CFBundle](https://developer.apple.com/documentation/corefoundation/cfbundle)
199-- [Apple: Bundle Configuration](https://developer.apple.com/documentation/bundleresources/information_property_list/bundle_configuration)
200-- [Apple: Resource Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Introduction/Introduction.html)
201-- [Apple: Bundle Programming Guide](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html)
217+ * [Apple: NSBundle class](<https://developer.apple.com/documentation/foundation/nsbundle>)
218+ * [Apple: Bundle Resources](<https://developer.apple.com/documentation/bundleresources/>)
219+ * [Apple: CFBundle](<https://developer.apple.com/documentation/corefoundation/cfbundle>)
220+ * [Apple: Bundle Configuration](<https://developer.apple.com/documentation/bundleresources/information_property_list/bundle_configuration>)
221+ * [Apple: Resource Programming Guide](<https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Introduction/Introduction.html>)
222+ * [Apple: Bundle Programming Guide](<https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html>)
202223
203224---
204-*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).*
225+*From the Free Pascal wiki, page "Application Bundle", as the Internet Archive kept it on 2023-01-29. 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