GNU Emacs
Emacs
Emacs and macOS / GNUstep

Emacs and macOS / GNUstep

This section describes the peculiarities of using Emacs built with the GNUstep libraries on GNU/Linux or other operating systems, or on macOS with native window system support. On macOS, Emacs can be built either without window system support, with X11, or with the Cocoa interface; this section only applies to the Cocoa build. This does not support versions before macOS 10.6. GNUstep is free software; macOS is not. Because it is a non-free operating system, macOS denies its users the freedom that every computer user deserves. That is an injustice. For your freedom's sake, we urge you to switch to a free operating system. We support GNU Emacs on proprietary operating systems because we hope this taste of freedom will inspire users to escape from them. For various historical and technical reasons, Emacs uses the term Nextstep internally, instead of "Cocoa" or "macOS"; for instance, most of the commands and variables described in this section begin with ns-, which is short for Nextstep. NeXTstep was an application interface released by NeXT Inc. during the 1980s, of which Cocoa is a direct descendant. Apart from Cocoa, there is another NeXTstep-style system: GNUstep, which is free software. As of this writing, Emacs GNUstep support is in alpha status (GNUstep Support), but we hope to improve it in the future.

Basic Emacs usage under macOS and GNUstep

By default, the Alt and Option keys are the same as Meta. The Mac Cmd key is the same as Super, and Emacs provides a set of key bindings using this modifier key that mimic other Mac / GNUstep applications (Mac / GNUstep Events). You can change these bindings in the usual way (Key Bindings). The modifiers themselves can be customized; Mac / GNUstep Customization. S-mouse-1 adjusts the region to the click position, just like mouse-3 (mouse-save-then-kill); it does not pop up a menu for changing the default face, as S-mouse-1 normally does (Text Scale). This change makes Emacs behave more like other Mac / GNUstep applications. When you open or save files using the menus, or using the Cmd-o and Cmd-S bindings, Emacs uses graphical file dialogs to read file names. However, if you use the regular Emacs key sequences, such as C-x C-f, Emacs uses the minibuffer to read file names. On GNUstep, in an X-windows environment you need to use Cmd-c instead of one of the C-w or M-w commands to transfer text to the X primary selection; otherwise, Emacs will use the clipboard selection. Likewise, Cmd-y (instead of C-y) yanks from the X primary selection instead of the kill-ring or clipboard.

Grabbing environment variables

Many programs which may run under Emacs, like latex or man, depend on the settings of environment variables. If Emacs is launched from the shell, it will automatically inherit these environment variables and its subprocesses will inherit them from it. But if Emacs is launched from the Finder it is not a descendant of any shell, so its environment variables haven't been set, which often causes the subprocesses it launches to behave differently than they would when launched from the shell. For the PATH and MANPATH variables, a system-wide method of setting PATH is recommended on macOS, using the /etc/paths files and the /etc/paths.d directory.

Mac / GNUstep Customization

There are a few customization options that are specific to the Nextstep port. For example, they affect things such as the modifier keys and the fullscreen behavior. To see all such options, use M-x customize-group RET ns RET.

Modifier keys

The following variables control the behavior of the actual modifier keys:

ns-alternate-modifier, ns-right-alternate-modifier
The left and right Option or Alt keys.
ns-command-modifier, ns-right-command-modifier
The left and right Command keys.
ns-control-modifier, ns-right-control-modifier
The left and right Control keys.
ns-function-modifier
The Function (fn) key.

The value of each variable is either a symbol, describing the key for any purpose, or a list of the form (:ordinary symbol :function symbol :mouse symbol), which describes the modifier when used with ordinary keys, function keys (that do not produce a character, such as arrow keys), and mouse clicks. If the symbol is one of control, meta, alt, super or hyper, this describes the Emacs modifier it represents. If symbol is none, Emacs does not use the key, which retains its standard behavior. For instance, the Option key in macOS is then used for composing additional characters. The variables for right-hand keys, like ns-right-alternate-modifier, may also be set to left, which means to use the same behavior as the corresponding left-hand key.

Frame Variables

ns-use-proxy-icon
This variable specifies whether to display the proxy icon in the titlebar. The proxy icon can be used to drag the file associated with the current buffer to other applications, a printer, the desktop, etc., in the same way you can from Finder. You might have to disable tool-bar-mode to see the proxy icon.
ns-confirm-quit
This variable specifies whether to display a graphical confirmation dialog on quitting.
ns-auto-hide-menu-bar
This variable specifies whether the macOS menu bar is hidden when an Emacs frame is selected. If non-nil the menu bar is not shown unless the mouse pointer is moved near to the top of the screen.
ns-use-native-fullscreen
This variable controls whether to use native, or non-native fullscreen. Native fullscreen is only available on macOS 10.7 and above.

macOS Trackpad/Mousewheel Variables

These variables only apply to macOS 10.7 (Lion) and above.

ns-use-mwheel-acceleration
This variable controls whether Emacs ignores the system mousewheel acceleration. When nil each `click' of the mousewheel will correspond exactly with one mousewheel event. When non-nil, the default, each `click' may correspond with more than one mousewheel event, depending on the user's input.
ns-use-mwheel-momentum
This variable controls whether Emacs ignores the system `momentum' when scrolling using a trackpad. When non-nil, the default, scrolling rapidly may result in the buffer continuing to scroll for a short while after the user has lifted their fingers off the trackpad.
ns-mwheel-line-height
This variable controls the sensitivity of scrolling with the trackpad. Apple trackpads scroll by pixels, not lines, so Emacs converts the system's pixel values into lines. When set to a number, this variable sets the number of pixels Emacs will consider as one line. When nil or a non-number the default line height is used. Setting a lower number makes the trackpad more sensitive, and a higher number makes the trackpad less sensitive.

Windowing System Events under macOS / GNUstep

Nextstep applications receive a number of special events which have no X equivalent. These are sent as specially defined key events, which do not correspond to any sequence of keystrokes. Under Emacs, these key events can be bound to functions just like ordinary keystrokes. Here is a list of these events.

ns-open-file
This event occurs when another Nextstep application requests that Emacs open a file. A typical reason for this would be a user double-clicking a file in the Finder application. By default, Emacs responds to this event by opening a new frame and visiting the file in that frame (ns-find-file). As an exception, if the selected buffer is the *scratch* buffer, Emacs visits the file in the selected frame. You can change how Emacs responds to a ns-open-file event by changing the variable ns-pop-up-frames. Its default value, fresh, is what we have just described. A value of t means to always visit the file in a new frame. A value of nil means to always visit the file in the selected frame.
ns-open-temp-file
This event occurs when another application requests that Emacs open a temporary file. By default, this is handled by just generating a ns-open-file event, the results of which are described above.
ns-open-file-line
Some applications, such as ProjectBuilder and gdb, request not only a particular file, but also a particular line or sequence of lines in the file. Emacs handles this by visiting that file and highlighting the requested line (ns-open-file-select-line).
ns-power-off
This event occurs when the user logs out and Emacs is still running, or when "Quit Emacs" is chosen from the application menu. The default behavior is to save all file-visiting buffers.
ns-show-prefs
This event occurs when the user selects "Preferences" from the application menu. By default, it is bound to the command customize.

Emacs also allows users to make use of Nextstep services, via a set of commands whose names begin with ns-service- and end with the name of the service. Type M-x ns-service- TAB to see a list of these commands. These functions either operate on marked text (replacing it with the result) or take a string argument and return the result as a string. You can also use the Lisp function ns-perform-service to pass arbitrary strings to arbitrary services and receive the results back. Note that you may need to restart Emacs to access newly-available services.

GNUstep Support

Emacs can be built and run under GNUstep, but there are still issues to be addressed. Interested developers should contact the emacs-devel mailing list.

Manual
Emacs 31.0.90
Texinfo Node
Mac OS / GNUstep
Source Ref
emacs-31.0.90
Source
View upstream