Difference between revisions of "Application Bundle"

From Lazarus wiki
Jump to navigationJump to search
m (Expanded application bundle description)
m (→‎From within Lazarus: Adjust heading)
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Platform only|macOS}}
 
 
{{Application Bundle}}
 
{{Application Bundle}}
  
Application Bundle is a directory with the extension ".app", with special purpose on macOS systems. It contains the application executable, resource files, help files and information about the application and is necessary for the correct execution of applications. 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 by using scripts.
+
== Overview ==
 +
 
 +
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.
 +
 
 +
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 QAt) by using scripts.
  
=== Overview ===
 
 
You can learn more about application bundles in the Apple [https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW19 Bundle Programming Guide].
 
You can learn more about application bundles in the Apple [https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW19 Bundle Programming Guide].
  
Application (bundle) settings are located in the property list file: Info.plist located in the bundle.app/Contents/ directory.
+
Application (bundle) settings are located in the property list file: [[macOS property list files|Info.plist]] located in the bundle.app/Contents/ directory.
  
To access it, you need to right click (ctrl-left click) on a bundle and select ''Show Package Contents''
+
To access the application bundle, you need to right click (ctrl-left click) on a bundle and select ''Show Package Contents''
  
 
[[Image:openbundle.png]]
 
[[Image:openbundle.png]]
Line 15: Line 17:
 
[[Image:infoplist.png]]
 
[[Image:infoplist.png]]
  
You can learn about property lists in the Apple [https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html Information Property List Key Reference].
+
== Application bundle layout ==
 +
 
 +
The basic structure of a Mac application bundle:
 +
 
 +
MyApp.app/
 +
    Contents/
 +
      Info.plist
 +
      MacOS/
 +
      Resources/
 +
 
 +
{| class="wikitable"
 +
! Sub-Directory of the Contents directory !! Usage description
 +
|-
 +
|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.
 +
|-
 +
|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#Bundle_layouts|Adding a Help Book - Bundle layouts]].
 +
|-
 +
|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]].
 +
|-
 +
|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.
 +
|-
 +
|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.
 +
|}
 +
 
 +
== Creating the Application Bundle ==
 +
 
 +
=== From within Lazarus ===
 +
 
 +
Open a project and go to Project -> Project Options -> Application tab and push the [[IDE_Window:_Project_Options#Application_Settings|Create Application Bundle]] button. The resulting Application Bundle will contain a symbolic link to the real executable.
 +
 
 +
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.
 +
 
 +
=== Via the command-line tool shipped with Lazarus ===
  
=== Creating Application Bundle ===
+
Open /Library/Lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.
  
==== From Lazarus ====
+
Open a Terminal of your choice and type:
Open project and go to Project -> Project Options -> Application tab and push the [[IDE Window: Project Options#Create Application Bundle|Create Application Bundle]] button. The resulted Application Bundle will have inside symbolic link to the real executable.
 
  
==== Via command-line tool shipped with Lazarus ====
 
Open lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.
 
Open a Terminal of your choice. Type:
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
cd project1/
 
cd project1/
lazarus/components/macfiles/examples/createmacapplication project1
+
/Library/Lazarus/components/macfiles/examples/createmacapplication project1
 
ln -s ../../../project1 project1.app/Contents/MacOS/project1
 
ln -s ../../../project1 project1.app/Contents/MacOS/project1
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== Use shell script ====
+
=== Via a shell script ===
  
 
You can adapt the following shell script to create a customized application bundle for your application. It allows the creation of either debug or release bundle.
 
You can adapt the following shell script to create a customized application bundle for your application. It allows the creation of either debug or release bundle.
Line 95: Line 125:
 
   mkdir $appfolder/Contents
 
   mkdir $appfolder/Contents
 
   mkdir $appfolder/Contents/MacOS
 
   mkdir $appfolder/Contents/MacOS
 +
  mkdir $appfolder/Contents/Frameworks  # optional, for including libraries or frameworks
 
   mkdir $appfolder/Contents/Resources
 
   mkdir $appfolder/Contents/Resources
  
Line 144: Line 175:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Executing application via Application Bundle ===
+
== Executing an application via the Application Bundle ==
 +
 
 +
You can start the application from the IDE, via its Finder icon or in the native macOS Terminal.app via "open project1.app".
 +
 
 +
== See also ==
 +
 
 +
* [[macOS property list files]]
 +
* [[Add an Apple Help Book to your macOS app]]
 +
* [[Hiding a macOS app from the Dock]]
 +
 
 +
== External links ==
  
You can start the application from IDE (checked option [[IDE_Window: Project Options#Use Application Bundle for running and debugging (darwin only)|Use Application Bundle for running and debugging (darwin only)]]) or via its Finder icon or in the native Mac OS X Terminal via "open project1.app".
+
* [https://developer.apple.com/documentation/foundation/nsbundle Apple: NSBundle class]
 +
* [https://developer.apple.com/documentation/bundleresources/ Apple: Bundle Resources]
 +
* [https://developer.apple.com/documentation/corefoundation/cfbundle Apple: CFBundle]
 +
* [https://developer.apple.com/documentation/bundleresources/information_property_list/bundle_configuration Apple: Bundle Configuration]
 +
* [https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Introduction/Introduction.html Apple: Resource Programming Guide]
 +
* [https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html Apple: Bundle Programming Guide]

Revision as of 06:45, 28 June 2020

English (en) 日本語 (ja) русский (ru)

macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide


Overview

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.

From within Lazarus it is used for the Carbon and Cocoa interfaces, but one can also build applications with other interfaces (eg Gtk or QAt) by using scripts.

You can learn more about application bundles in the Apple Bundle Programming Guide.

Application (bundle) settings are located in the property list file: Info.plist located in the bundle.app/Contents/ directory.

To access the application bundle, you need to right click (ctrl-left click) on a bundle and select Show Package Contents

openbundle.png

infoplist.png

Application bundle layout

The basic structure of a Mac application bundle:

MyApp.app/
   Contents/
      Info.plist
      MacOS/
      Resources/
Sub-Directory of the Contents directory Usage description
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.
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 Adding a Help Book - Bundle layouts.
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.
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.
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.

Creating the Application Bundle

From within Lazarus

Open a project and go to Project -> Project Options -> Application tab and push the Create Application Bundle button. The resulting Application Bundle will contain a symbolic link to the real executable.

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.

Via the command-line tool shipped with Lazarus

Open /Library/Lazarus/components/macfiles/examples/createmacapplication.lpi in the IDE. Compile.

Open a Terminal of your choice and type:

cd project1/
/Library/Lazarus/components/macfiles/examples/createmacapplication project1
ln -s ../../../project1 project1.app/Contents/MacOS/project1

Via a shell script

You can adapt the following shell script to create a customized application bundle for your application. It allows the creation of either debug or release bundle.

  • In the debug bundle, a link to the executable is placed, allowing for debugging using the Lazarus IDE,
  • In the release bundle, the executable is copied so the application bundle as a whole can be used stand-alone/copied to other locations.
#!/bin/sh
# Force Bourne shell in case tcsh is default.
#

#
# Reads the bundle type
#

echo "========================================================"
echo "    Bundle creation script"
echo "========================================================"
echo ""
echo " Please select which kind of bundle you would like to build:"
echo ""
echo " 1 > Debug bundle"
echo " 2 > Release bundle"
echo " 0 > Exit"

read command

case $command in

  1) ;;

  2) ;;
  
  0) exit 0;;

  *) echo "Invalid command"
     exit 0;;

esac

#
# Creates the bundle
#

appname=Magnifier
appfolder=$appname.app
macosfolder=$appfolder/Contents/MacOS
plistfile=$appfolder/Contents/Info.plist
appfile=magnifier

PkgInfoContents="APPLMAG#"

#
if ! [ -e $appfile ]
then
  echo "$appfile does not exist"
elif [ -e $appfolder ]
then
  echo "$appfolder already exists"
else
  echo "Creating $appfolder..."
  mkdir $appfolder
  mkdir $appfolder/Contents
  mkdir $appfolder/Contents/MacOS
  mkdir $appfolder/Contents/Frameworks  # optional, for including libraries or frameworks
  mkdir $appfolder/Contents/Resources

#
# For a debug bundle,
# Instead of copying executable into .app folder after each compile,
# simply create a symbolic link to executable.
#
if [ $command = 1 ]; then
  ln -s ../../../$appname $macosfolder/$appname
else
  cp $appname $macosfolder/$appname
fi  

# Copy the resource files to the correct place
  cp *.bmp $appfolder/Contents/Resources
  cp icon3.ico $appfolder/Contents/Resources
  cp icon3.png $appfolder/Contents/Resources
  cp macicon.icns $appfolder/Contents/Resources
  cp docs/*.* $appfolder/Contents/Resources
#
# Create PkgInfo file.
  echo $PkgInfoContents >$appfolder/Contents/PkgInfo
#
# Create information property list file (Info.plist).
  echo '<?xml version="1.0" encoding="UTF-8"?>' >$plistfile
  echo '<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >>$plistfile
  echo '<plist version="1.0">' >>$plistfile
  echo '<dict>' >>$plistfile
  echo '  <key>CFBundleDevelopmentRegion</key>' >>$plistfile
  echo '  <string>English</string>' >>$plistfile
  echo '  <key>CFBundleExecutable</key>' >>$plistfile
  echo '  <string>'$appname'</string>' >>$plistfile
  echo '  <key>CFBundleIconFile</key>' >>$plistfile
  echo '  <string>macicon.icns</string>' >>$plistfile
  echo '  <key>CFBundleIdentifier</key>' >>$plistfile
  echo '  <string>org.magnifier.magnifier</string>' >>$plistfile
  echo '  <key>CFBundleInfoDictionaryVersion</key>' >>$plistfile
  echo '  <string>6.0</string>' >>$plistfile
  echo '  <key>CFBundlePackageType</key>' >>$plistfile
  echo '  <string>APPL</string>' >>$plistfile
  echo '  <key>CFBundleSignature</key>' >>$plistfile
  echo '  <string>MAG#</string>' >>$plistfile
  echo '  <key>CFBundleVersion</key>' >>$plistfile
  echo '  <string>1.0</string>' >>$plistfile
  echo '</dict>' >>$plistfile
  echo '</plist>' >>$plistfile
fi

Executing an application via the Application Bundle

You can start the application from the IDE, via its Finder icon or in the native macOS Terminal.app via "open project1.app".

See also

External links