001: @c This is part of the Emacs manual.
002: @c Copyright (C) 2000-2019 Free Software Foundation, Inc.
003: @c See file emacs.texi for copying conditions.
004: @node Mac OS / GNUstep
005: @appendix Emacs and macOS / GNUstep
006: @cindex macOS
007: @cindex Macintosh
008: @cindex GNUstep
009: 
010:   This section describes the peculiarities of using Emacs built with
011: the GNUstep libraries on GNU/Linux or other operating systems, or on
012: macOS with native window system support.  On macOS, Emacs can be
013: built either without window system support, with X11, or with the
014: Cocoa interface; this section only applies to the Cocoa build.  This
015: does not support versions before macOS 10.6.
016: 
017:   GNUstep is free software; macOS is not.  Because it is a non-free
018: operating system, macOS denies its users the freedom that every computer
019: user deserves.  That is an injustice.  For your freedom's sake, we
020: urge you to switch to a free operating system.
021: 
022:   We support GNU Emacs on proprietary operating systems because
023: we hope this taste of freedom will inspire users to escape from them.
024: 
025:   For various historical and technical reasons, Emacs uses the term
026: @samp{Nextstep} internally, instead of ``Cocoa'' or ``macOS''; for
027: instance, most of the commands and variables described in this section
028: begin with @samp{ns-}, which is short for @samp{Nextstep}.  NeXTstep
029: was an application interface released by NeXT Inc.@: during the 1980s,
030: of which Cocoa is a direct descendant.  Apart from Cocoa, there is
031: another NeXTstep-style system: GNUstep, which is free software.  As of
032: this writing, Emacs GNUstep support is in alpha status (@pxref{GNUstep
033: Support}), but we hope to improve it in the future.
034: 
035: @menu
036: * Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or macOS.
037: * Mac / GNUstep Customization:: Customizations under GNUstep or macOS.
038: * Mac / GNUstep Events::        How window system events are handled.
039: * GNUstep Support::             Details on status of GNUstep support.
040: @end menu
041: 
042: @node Mac / GNUstep Basics
043: @section Basic Emacs usage under macOS and GNUstep
044: 
045: @cindex modifier keys (macOS)
046:   By default, the @key{Alt} and @key{Option} keys are the same as
047: @key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
048: Emacs provides a set of key bindings using this modifier key that mimic
049: other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}).  You
050: can change these bindings in the usual way (@pxref{Key Bindings}).
051: 
052: @vindex ns-alternate-modifier
053: @vindex ns-right-alternate-modifier
054:   The variable @code{ns-right-alternate-modifier} controls the
055: behavior of the right @key{Alt} and @key{Option} keys.  These keys
056: behave like the left-hand keys if the value is @code{left} (the
057: default).  A value of @code{control}, @code{meta}, @code{alt},
058: @code{super}, or @code{hyper} makes them behave like the corresponding
059: modifier keys; a value of @code{left} means be the same key as
060: @code{ns-alternate-modifier}; a value of @code{none} tells Emacs to
061: ignore them, in which case you get the default behavior of macOS
062: accentuation system from the right @key{Option} key.
063: 
064:   @kbd{S-mouse-1} adjusts the region to the click position,
065: just like @kbd{mouse-3} (@code{mouse-save-then-kill}); it does not pop
066: up a menu for changing the default face, as @kbd{S-mouse-1} normally
067: does (@pxref{Text Scale}).  This change makes Emacs behave more like
068: other Mac / GNUstep applications.
069: 
070:   When you open or save files using the menus, or using the
071: @kbd{Cmd-o} and @kbd{Cmd-S} bindings, Emacs uses graphical file
072: dialogs to read file names.  However, if you use the regular Emacs key
073: sequences, such as @kbd{C-x C-f}, Emacs uses the minibuffer to read
074: file names.
075: 
076: @cindex copy/paste to/from primary selection (macOS)
077:   On GNUstep, in an X-windows environment you need to use @kbd{Cmd-c}
078: instead of one of the @kbd{C-w} or @kbd{M-w} commands to transfer text
079: to the X primary selection; otherwise, Emacs will use the
080: clipboard selection.  Likewise, @kbd{Cmd-y} (instead of @kbd{C-y})
081: yanks from the X primary selection instead of the kill-ring or
082: clipboard.
083: 
084: 
085: @subsection Grabbing environment variables
086: 
087: @c How is this any different to launching from a window manager menu
088: @c in GNU/Linux?  These are sometimes not login shells either.
089: @cindex environment variables (macOS)
090: Many programs which may run under Emacs, like latex or man, depend on the
091: settings of environment variables.  If Emacs is launched from the shell, it
092: will automatically inherit these environment variables and its subprocesses
093: will inherit them from it.  But if Emacs is launched from the Finder it
094: is not a descendant of any shell, so its environment variables haven't been
095: set, which often causes the subprocesses it launches to behave differently than
096: they would when launched from the shell.
097: 
098: For the PATH and MANPATH variables, a system-wide method
099: of setting PATH is recommended on macOS, using the
100: @file{/etc/paths} files and the @file{/etc/paths.d} directory.
101: 
102: @node Mac / GNUstep Customization
103: @section Mac / GNUstep Customization
104: 
105: There are a few customization options that are specific to the
106: Nextstep port.  For example, they affect things such as the modifier
107: keys and the fullscreen behavior.  To see all such options, use
108: @kbd{M-x customize-group @key{RET} ns @key{RET}}.
109: 
110: @subsection Font Panel
111: 
112: @findex ns-popup-font-panel
113: The standard Mac / GNUstep font panel is accessible with @kbd{M-x
114: ns-popup-font-panel} and will set the default font in the frame most
115: recently used or clicked on.
116: 
117: @c  To make the setting permanent, use @samp{Save Options} in the
118: @c Options menu, or run @code{menu-bar-options-save}.
119: 
120: @cindex Core Text, on macOS
121: @cindex font backend, on macOS
122: In macOS, Emacs uses a Core Text based font backend
123: by default.  If you prefer the older font style, enter the following
124: at the command-line before starting Emacs:
125: 
126: @example
127: % defaults write org.gnu.Emacs FontBackend ns
128: @end example
129: 
130: 
131: @node Mac / GNUstep Events
132: @section Windowing System Events under macOS / GNUstep
133: @cindex events on macOS
134: 
135:   Nextstep applications receive a number of special events which have
136: no X equivalent.  These are sent as specially defined key events, which
137: do not correspond to any sequence of keystrokes.  Under Emacs, these
138: key events can be bound to functions just like ordinary
139: keystrokes.  Here is a list of these events.
140: 
141: @table @key
142: @item ns-open-file
143: @vindex ns-pop-up-frames
144: This event occurs when another Nextstep application requests that
145: Emacs open a file.  A typical reason for this would be a user
146: double-clicking a file in the Finder application.  By default, Emacs
147: responds to this event by opening a new frame and visiting the file in
148: that frame (@code{ns-find-file}).  As an exception, if the selected
149: buffer is the @file{*scratch*} buffer, Emacs visits the file in the
150: selected frame.
151: 
152: You can change how Emacs responds to a @code{ns-open-file} event by
153: changing the variable @code{ns-pop-up-frames}.  Its default value,
154: @samp{fresh}, is what we have just described.  A value of @code{t}
155: means to always visit the file in a new frame.  A value of @code{nil}
156: means to always visit the file in the selected frame.
157: 
158: @item ns-open-temp-file
159: This event occurs when another application requests that Emacs open a
160: temporary file.  By default, this is handled by just generating a
161: @code{ns-open-file} event, the results of which are described above.
162: 
163: @item ns-open-file-line
164: Some applications, such as ProjectBuilder and gdb, request not only a
165: particular file, but also a particular line or sequence of lines in
166: the file.  Emacs handles this by visiting that file and highlighting
167: the requested line (@code{ns-open-file-select-line}).
168: 
169: @item ns-drag-n-drop
170: This event occurs when a user drags an object from another application
171: into an Emacs frame.  The default behavior is to open a file in the
172: window under the mouse, or to insert text at point of the window under
173: the mouse.
174: 
175: The sending application has some limited ability to decide how Emacs
176: handles the sent object, but the user may override the default
177: behaviour by holding one or more modifier key.
178: 
179: @table @kbd
180: @item control
181: Insert as text in the current buffer.  If the object is a file, this
182: will insert the filename.
183: @item alt/option
184: Attempt to open the object as though it is a file or URL.
185: @item super/command
186: Perform the default action for the type.  This can be useful when an
187: application is overriding the default behaviour.
188: @end table
189: 
190: The modifier keys listed above are defined by macOS and are unaffected
191: by user changes to the modifiers in Emacs.
192: 
193: @item ns-change-font
194: This event occurs when the user selects a font in a Nextstep font
195: panel (which can be opened with @kbd{Cmd-t}).  The default behavior is
196: to adjust the font of the selected frame
197: (@code{ns-respond-to-changefont}).  The name and size of the selected
198: font are stored in the variables @code{ns-input-font} and
199: @code{ns-input-fontsize}, respectively.
200: 
201: @item ns-power-off
202: This event occurs when the user logs out and Emacs is still running, or when
203: ``Quit Emacs'' is chosen from the application menu.
204: The default behavior is to save all file-visiting buffers.
205: @end table
206: 
207: @cindex using Nextstep services (macOS)
208:   Emacs also allows users to make use of Nextstep services, via a set
209: of commands whose names begin with @samp{ns-service-} and end with the
210: name of the service.  Type @kbd{M-x ns-service-@key{TAB}} to
211: see a list of these commands.  These functions either operate on
212: marked text (replacing it with the result) or take a string argument
213: and return the result as a string.  You can also use the Lisp function
214: @code{ns-perform-service} to pass arbitrary strings to arbitrary
215: services and receive the results back.  Note that you may need to
216: restart Emacs to access newly-available services.
217: 
218: @node GNUstep Support
219: @section GNUstep Support
220: 
221: Emacs can be built and run under GNUstep, but there are still
222: issues to be addressed.  Interested developers should contact
223: @ifnothtml
224: @email{emacs-devel@@gnu.org}.
225: @end ifnothtml
226: @ifhtml
227: @url{https://lists.gnu.org/mailman/listinfo/emacs-devel, the
228: emacs-devel mailing list}.
229: @end ifhtml
230: