6 Delivery on macOS

This chapter describes several issues relevant to delivery with LispWorks for Macintosh.

6.1 Universal binaries

The supplied LispWorks (64-bit) for Macintosh image are a universal binaries, which run the correct native architecture on arm64 (Apple silicon) and x86_64 (Intel) Macintosh computers by default. To deliver a universal binary application from LispWorks (64-bit) for Macintosh, you will need an Apple silicon Macintosh computer. You can specify a universal binary build in the Application Builder tool (see 28 The Application Builder in the LispWorks IDE User Guide) or call save-universal-from-script directly (see the LispWorks® User Guide and Reference Manual).

6.2 Application bundles

deliver creates a single executable file. However graphical Macintosh applications consist of an application bundle, which is a folder Foo.app with several subfolders containing the main executable and other resources.

LispWorks for Macintosh contains a function that constructs an application bundle. You can use this such that your executable is delivered ready to run in its application bundle in the usual macOS way. See 13.3 Creating a macOS application bundle for an illustration of this.

6.3 Bad interaction with clean-up utilities

Utilities which attempt to "clean up" your Mac by removing unused parts of an image can damage LispWorks itself and also LispWorks applications.

If you use such a utility on your LispWorks development machines, configure it to ignore LispWorks.

If you distribute a LispWorks application, document that it may be damaged by utilities which attempt to clean up a Mac by removing unused parts of an image. To prevent this, such utilities should be configured to ignore the LispWorks application.

As an example, CleanMyMac has an Ignore List which includes LispWorks by default, but will not include your LispWorks runtime application until you add it.

6.4 Cocoa and GTK+ images

LispWorks for Macintosh is supplied with two images. One supports the Cocoa GUI, the other supports the GTK+ GUI (and can load the Motif GUI). You cannot build a Cocoa application using the GTK+ LispWorks image, and vice versa.

You should use the appropriate image to deliver your application.

For GTK+ and Motif applications delivered with LispWorks for Macintosh, the issues described in 8 Delivery on Linux, FreeBSD and x86/x64 Solaris will be relevant.

6.5 Terminal windows and message logs

6.5.1 Controlling use of a terminal window

A graphical Macintosh application does not usually have a console/terminal window.

You can achieve this by supplying the keyword argument :console :input when delivering your application.

6.5.2 Logging debugging messages

Output to *terminal-io* from an application without a console/terminal window will not ordinarily be visible to the user, so debugging messages should be written to a log file.

Log files are recommended for any complex application as they make it easier for you to get information back from your users.

You can use dbg:log-bug-form for logging errors. See the LispWorks® User Guide and Reference Manual for details.

6.6 File associations for a Macintosh application

To create an association between your LispWorks for Macintosh application and files with a specified type (file extension):

Create the appropriate entries for the file type in the CFBundleDocumentTypes array within the Info.plist file of the delivered application.
Define a subclass of capi:cocoa-default-application-interface with a message-callback.
Implement the :open-file message in the message-callback function.
Set the application interface on startup.

Also see the examples mentioned in 15.1 Delivering a Cocoa CAPI application examples.

6.7 Editor emulation

If your application uses capi:editor-pane or its subclasses, your should consider the input style. The editor in the delivered application can emulate Emacs or macOS style editing. The deliver keyword :editor-style controls which emulation is used.

6.8 Standard Edit keyboard gestures

To implement the standard gestures Command+X, Command+C and Command+V in your CAPI/Cocoa runtime application, you must include an Edit menu explicitly in your capi:interface definition.

Note: The LispWorks IDE adds a minimal Edit menu to all CAPI interfaces automatically, in order to make these standard gestures work in the LispWorks IDE, but this does not persist after delivery.

6.9 Quitting a CAPI/Cocoa application

The application menu's quit callback (that is, the callback normally invoked by Command+Q) should simply call capi:destroy with the application interface and should not call lw:quit directly.

For an example see the Quit Multiple Window CAPI Application menu item in:

(example-edit-file "capi/applications/cocoa-application")

6.10 Retaining Objective-C classes

If you implement an Objective-C class in Lisp but its name is not referenced at run time, then you need to arrange for this symbol to be retained during delivery.

This can be achieved with :keep-symbols, but a more modular approach is to keep the name on the plist of some other symbol. For example the internal CAPI class lw-slider is defined like this:

(objc:define-objc-class lw-slider ()
    ()
  (:objc-class-name "LWSlider")
  (:objc-superclass-name "NSSlider"))

and lw-slider is retained like this:

(setf (get 'slider-representation 'owner-class)
      'lw-slider)

In this case, the code for slider-representation is the only thing that makes the LWSlider object, so it is the best place to retain it (that is, only if slider-representation is retained).

6.11 X11/Motif considerations

The default double-click (and triple-click) speed for X11 applications is 200ms, whereas the default for Macintosh applications is typically 500ms.

To match this in your configuration, add a line:

*.multiClickTime: 500

in the Xresources file.

6.12 Examples of delivering Cocoa applications

Several self-contained examples in the LispWorks library illustrate delivering a CAPI/Cocoa application, listed in 15 Self-contained examples of delivery.