Sign in Join
Wiki copytemporary

Application Bundle: what changed

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

OldNewLine
11## Overview
22
33An 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.
44
55From 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.
66
77You can learn more about application bundles in the Apple Bundle Programming Guide.
88
99Application (bundle) settings are located in the property list file: [[macOS property list files|Info.plist]] located in the `bundle.app/Contents/` directory.
1010
1111The **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”.
1212
1313To access the application bundle contents in Finder, you need to right click (ctrl-left click) on a bundle and select *Show Package Contents*
1414
15-<figure>
16-<img src="openbundle.png" title="openbundle.png" />
17-<figcaption>openbundle.png</figcaption>
18-</figure>
15+![](/wiki-images/1/12/Openbundle.png)
1916
20-<figure>
21-<img src="infoplist.png" title="infoplist.png" />
22-<figcaption>infoplist.png</figcaption>
23-</figure>
17+![](/wiki-images/8/81/Infoplist.png)
2418
2519## Application bundle layout
2620
2721The basic structure of a Mac application bundle:
2822
2923`MyApp.app/`\
3024`   Contents/`\
3125`      Info.plist`\
3226`      MacOS/`\
3327`      PkgInfo`\
3428`      Resources/`
3529
3630| Sub-Directory of the Contents directory | Usage description |
3731|----|----|
3832| 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. |
3933| 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]]. |
4034| 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]]. |
4135| 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. |
4236| 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. |
4337
4438## Creating the Application Bundle
4539
4640### Using Lazarus
4741
4842Open 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.
4943
5044> **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.
5145
5246### Using the Lazarus command-line tool
5347
5448Open `/Applications/Lazarus/components/macfiles/examples/createmacapplication.lpi` in the Lazarus IDE. Compile.
5549
5650Open a Terminal of your choice and type:
5751
5852``` bash
5953cd project1/
6054/Applications/Lazarus/components/macfiles/examples/createmacapplication project1
6155ln -s ../../../project1 project1.app/Contents/MacOS/project1
6256```
6357
6458### Using a shell script
6559
6660You 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.
6761
6862- In the debug bundle, a link to the executable is placed, allowing for debugging using the Lazarus IDE,
6963- In the release bundle, the executable is copied so the application bundle as a whole can be used stand-alone/copied to other locations.
7064
7165``` bash
7266#!/bin/sh
7367# Force Bourne shell in case tcsh is default.
7468#
7569
7670#
7771# Reads the bundle type
7872#
7973
8074echo "========================================================"
8175echo " Bundle creation script"
8276echo "========================================================"
8377echo ""
8478echo " Please select which kind of bundle you would like to build:"
8579echo ""
8680echo " 1 > Debug bundle"
8781echo " 2 > Release bundle"
8882echo " 0 > Exit"
8983
9084read command
9185
9286case $command in
9387
9488 1) ;;
9589
9690 2) ;;
9791
9892 0) exit 0;;
9993
10094 *) echo "Invalid command"
10195 exit 0;;
10296
10397esac
10498
10599#
106100# Creates the bundle
107101#
108102
109103appname=Magnifier
110104appfolder=$appname.app
111105macosfolder=$appfolder/Contents/MacOS
112106plistfile=$appfolder/Contents/Info.plist
113107appfile=magnifier
114108
115109PkgInfoContents="APPL????"
116110
117111#
118112if ! [ -e $appfile ]
119113then
120114 echo "$appfile does not exist"
121115elif [ -e $appfolder ]
122116then
123117 echo "$appfolder already exists"
124118else
125119 echo "Creating $appfolder..."
126120 mkdir $appfolder
127121 mkdir $appfolder/Contents
128122 mkdir $appfolder/Contents/MacOS
129123 mkdir $appfolder/Contents/Frameworks # optional, for including libraries or frameworks
130124 mkdir $appfolder/Contents/Resources
131125
132126#
133127# For a debug bundle,
134128# Instead of copying executable into .app folder after each compile,
135129# simply create a symbolic link to executable.
136130#
137131if [ $command = 1 ]; then
138132 ln -s ../../../$appname $macosfolder/$appname
139133else
140134 cp $appname $macosfolder/$appname
141135fi
142136
143137# Copy the resource files to the correct place
144138 cp *.bmp $appfolder/Contents/Resources
145139 cp icon3.ico $appfolder/Contents/Resources
146140 cp icon3.png $appfolder/Contents/Resources
147141 cp macicon.icns $appfolder/Contents/Resources
148142 cp docs/*.* $appfolder/Contents/Resources
149143#
150144# Create PkgInfo file.
151145 echo $PkgInfoContents >$appfolder/Contents/PkgInfo
152146#
153147# Create information property list file (Info.plist).
154148 echo '<?xml version="1.0" encoding="UTF-8"?>' >$plistfile
155149 echo '<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >>$plistfile
156150 echo '<plist version="1.0">' >>$plistfile
157151 echo '<dict>' >>$plistfile
158152 echo ' <key>CFBundleDevelopmentRegion</key>' >>$plistfile
159153 echo ' <string>English</string>' >>$plistfile
160154 echo ' <key>CFBundleExecutable</key>' >>$plistfile
161155 echo ' <string>'$appname'</string>' >>$plistfile
162156 echo ' <key>CFBundleIconFile</key>' >>$plistfile
163157 echo ' <string>macicon.icns</string>' >>$plistfile
164158 echo ' <key>CFBundleIdentifier</key>' >>$plistfile
165159 echo ' <string>org.magnifier.magnifier</string>' >>$plistfile
166160 echo ' <key>CFBundleInfoDictionaryVersion</key>' >>$plistfile
167161 echo ' <string>6.0</string>' >>$plistfile
168162 echo ' <key>CFBundlePackageType</key>' >>$plistfile
169163 echo ' <string>APPL</string>' >>$plistfile
170164 echo ' <key>CFBundleSignature</key>' >>$plistfile
171165 echo ' <string>MAG#</string>' >>$plistfile
172166 echo ' <key>CFBundleVersion</key>' >>$plistfile
173167 echo ' <string>1.0</string>' >>$plistfile
174168 echo '</dict>' >>$plistfile
175169 echo '</plist>' >>$plistfile
176170fi
177171```
178172
179173## Executing an application via the Application Bundle
180174
181175You can start the application from the Lazarus IDE, by clicking on its Finder icon or in the native macOS Terminal.app by typing:
182176
183177``` bash
184178open project1.app
185179```
186180
187181or
188182
189183``` bash
190184./project1.app/Contents/MacOS/project1
191185```
192186
193187## See also
194188
195189- [[Add an Apple Help Book to your macOS app]]
196190- [[Deploying Your Application|Deploying your macOS application]]
197191- [[Hiding a macOS app from the Dock]]
198192- [[macOS property list files]]
199193
200194## External links
201195
202196- [Apple: NSBundle class](https://developer.apple.com/documentation/foundation/nsbundle)
203197- [Apple: Bundle Resources](https://developer.apple.com/documentation/bundleresources/)
204198- [Apple: CFBundle](https://developer.apple.com/documentation/corefoundation/cfbundle)
205199- [Apple: Bundle Configuration](https://developer.apple.com/documentation/bundleresources/information_property_list/bundle_configuration)
206200- [Apple: Resource Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Introduction/Introduction.html)
207201- [Apple: Bundle Programming Guide](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html)
208202
209203---
210204*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