13.3 Creating a macOS application bundle

The section applies only to LispWorks for Macintosh with the native Cocoa GUI.

You should not simply run a macOS/Cocoa GUI application from the command line in Terminal.app. Instead you should put the image in a suitable Application Bundle and run it using the Finder. The example delivery scripts in this manual create the Application Bundle before writing the executable.

The function hcl:create-macos-application-bundle does several things to construct a suitable macOS application bundle for your delivered image. It:

• Creates the folders comprising an Application Bundle.
• Adds the resources from a supplied template bundle (or LispWorks (64-bit).app) to the Application Bundle.
• Writes a suitable Info.plist file in the Application Bundle.
• Returns the path of the executable within the Application Bundle.

Note: You must supply identifier to provide CFBundleIdentifier when creating a bundle for your own application.

13.3.1 Example application bundle delivery script

Note how this script calls deliver with the executable path returned by hcl:create-macos-application-bundle:

(in-package "CL-USER")
(load-all-patches)
;; Compile and load othello example code
(compile-file (example-file "capi/applications/othello")
              :output-file :temp
              :load t)
;; Create Othello.app and deliver the executable inside it
(deliver 'play-othello 
         #+:cocoa
         (create-macos-application-bundle
          "~/Desktop/Othello.app"
          ;; Do not copy file associations...
          :document-types nil
          ;; ...or CFBundleIdentifier from the LispWorks bundle
          :identifier "com.example.Othello"
          )
         #-:cocoa "~/othello" 0 :interface :capi)

In the session below script.lisp is in the user's home directory. Here is the start and end of the session output in Terminal.app:

mymac:/Applications/LispWorks 8.0 (64-bit)/LispWorks (64-bit).app/Contents/MacOS % ./lispworks-8-0-0-macos64-universal -build ~/script.lisp
; Loading text file /Applications/LispWorks 8.0 (64-bit)/Library/lib/8-0-0-0/private-patches/load.lisp
LispWorks(R): The Common Lisp Programming Environment
Copyright (C) 1987-2021 LispWorks Ltd.  All rights reserved.
Version 8.0.0
Saved by LispWorks as lispworks-8-0-0-amd64-darwin-gtk, at 02 Aug 2021 15:21
User lw on mymacmachine.lispworks.com
; Loading text file /Users/lw/script.lisp
;  Loading text file /Applications/LispWorks 8.0 (64-bit)/Library/lib/8-0-0-0/private-patches/load.lisp
;;; Compiling file /Applications/LispWorks 8.0 (64-bit)/Library/lib/8-0-0-0/examples/capi/applications/othello ...
;;; Safety = 3, Speed = 1, Space = 1, Float = 1, Interruptible = 1
 
[... full compilation and delivery output not shown...]
 
Shaking stage : Saving image
Build saving image: /Users/lw/Desktop/Othello.app/Contents/MacOS/Othello
Build saved image: /Users/lw/Desktop/Othello.app/Contents/MacOS/Othello
 
Delivery successful - /Users/lw/Desktop/Othello.app/Contents/MacOS/Othello

The last line of the deliver output shows the full path to the executable, but you should run the application bundle Othello.app via the Finder.

13.3.2 Alternative application bundle creation code

Your LispWorks Library contains example code which constructs a macOS application bundle. It defines write-macos-application-bundle which is similar to hcl:create-macos-application-bundle.

LispWorks 5.1 and earlier versions relied on this example code to create macOS application bundles and you may still wish to use it, or a modified version of it, if hcl:create-macos-application-bundle does not meet your needs. Load the example file in your delivery script, before calling deliver, like this:

#+:cocoa
(compile-file
 (example-file "configuration/macos-application-bundle")
 :output-file :temp
 :load t)

There is another example, which is actually a save-image script (rather than deliver), in:

(example-file "configuration/save-macos-application.lisp")

13.3.3 Further macOS delivery examples

These can be found in your LispWorks library directory:

(example-edit-file "delivery/macos/")