This page is about the peculiarities of running Emacs as an application ("Emacs.app") on a Mac, GNUstep or OpenSTEP.
For the different variants of Emacs on Mac OSX, see EmacsForMacOS.

== How to Install ==

See "Cocoa Emacs" under EmacsForMacOS.


== PATH ==
=== PATH and exec-path===
See [http://www.gnu.org/software/emacs/manual/html_node/elisp/Subprocess-Creation.html www.gnu.org/software/emacs/manual/html_node/elisp/Subprocess-Creation.html], in particular "Generally, you should not modify exec-path directly. Instead, ensure that your PATH environment variable is set appropriately before starting Emacs. "

By default ##exec-path## in Emacs.app appears to be initialized to a list derived from PATH, plus ##exec-directory##, e.g. "/Applications/Emacs.app/Contents/MacOS/bin/".

===PATH set from Terminal===

If you launch Emacs.app from the terminal, e.g.

   /Applications/Emacs.app/Contents/MacOS/Emacs

then the Emacs PATH will be the Terminal PATH.

===PATH set from ~/.MacOSX/environment.plist===

##~/.MacOSX/environment.plist## can also be used as a central place to save environment variables for all processes launched by a user, including from Spotlight according to the Apple documentation at:
* [http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/EnvironmentVars.html  developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/EnvironmentVars.html]
* [http://developer.apple.com/qa/qa2001/qa1067.html  developer.apple.com/qa/qa2001/qa1067.html]

Note that there are reports that ##environment.plist## does not work in Lion/Mountain Lion.  Definitive Apple developer documentation on this would be welcome.

The ##defaults## program can be used to read and write to  ##~/.MacOSX/environment.plist##, for example:

	export PATH=$(defaults read "${HOME}/.MacOSX/environment" PATH)         # bash
	set path=(`defaults read ~/.MacOSX/environment PATH | tr ':' ' '`)           # tcsh

NOTE: when you make a change to ##environment.plist##, you need to log off and log in again before it takes effect.

For those that like their PATHs from ##.bashrc## and would like the ##environment.plist## to update itself at every start up, put the following in your ##/etc/profile## file:

    #/etc/profile begin
    if [ -x /usr/libexec/path_helper ]; then
        eval `/usr/libexec/path_helper -s`
        defaults write $HOME/.MacOSX/environment PATH "$PATH"
    fi
    #/etc/profile end

Other information.  
* [http://www.nabble.com/unicode-character-in-aquamacs-td24259615.html  www.nabble.com/unicode-character-in-aquamacs-td24259615.html]
* [http://superuser.com/questions/476752/setting-environment-variables-in-os-x-for-gui-applications  superuser.com/questions/476752/setting-environment-variables-in-os-x-for-gui-applications]
* [http://apple.stackexchange.com/questions/57385/where-are-system-environment-variables-set-in-mountain-lion apple.stackexchange.com/questions/57385/where-are-system-environment-variables-set-in-mountain-lion]

=== Alternative solution for ~/.MacOSX/environment.plist===

I found the above to be not quite right on my Mac OS 10.6 laptop.  The ##defaults## command generated gibberish in my ##environment.plist## file so I took the approach of creating a startup script (##~/bin/macosx-startup##) and added it to my User account login items list.  ##macosx-startup## is a bash one-liner:

    #!/bin/bash
    bash -l -c "/Applications/Emacs.app/Contents/MacOS/Emacs --batch -l ~/lib/emacs/elisp/macosx/environment-support.el -f generate-env-plist"

where ##environment-support.el## is:

{{{
;;; Provide support for the environment on Mac OS X

(defun generate-env-plist ()
  "Dump the current environment into the ~/.MacOSX/environment.plist file."
  ;; The system environment is found in the global variable:
  ;; 'initial-environment as a list of "KEY=VALUE" pairs.
  (let ((list initial-environment)
        pair start)
    ;; clear out the current environment settings
    (find-file "~/.MacOSX/environment.plist")
    (goto-char (point-min))
    (setq start (search-forward "<dict>\n"))
    (search-forward "</dict>")
    (beginning-of-line)
    (delete-region start (point))
    (while list
      (setq pair (split-string (car list) "=")
            list (cdr list))
      (insert "  <key>" (nth 0 pair) "</key>\n")
      (insert "  <string>" (nth 1 pair) "</string>\n"))
    ;; Save the buffer.
    (save-buffer)))
}}}

Note: You must create a dummy ##environment.plist## file to seed the process.

=== PATH set from launchd===

Because Spotlight's parent process is launchd, one can set environment variables for applications (including Emacs.app) launched from Spotlight by putting them in in ##/etc/launchd.conf## or ##$HOME/.launchd.conf##. The syntax is tcsh.
For example:

    % cat /etc/launchd.conf 
    # include macports in global path - basically so Emacs.app can see git
    setenv PATH /opt/local/bin:/opt/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin

You will have to reboot for launchd to reload ##launchd.conf##. If you don't want to do that, you can use ##launchctl setenv## to set environment variables for launchd like so:

    % launchctl setenv PATH /opt/local/bin:/opt/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin

Under OS X 10.8, /etc/launchd.conf does not exist by default, so you may have to create it.  Also, you can inherit the path other system changes may provide using the path_helper utility:

    % echo \`/usr/libexec/path_helper -c\` | sudo bash -c "cat - >> /etc/launchd.conf"

=== PATH set from Info.plist in app bundle ===

For current versions of macOS (10.14 Mojave and before) [https://developer.apple.com/documentation/bundleresources/information_property_list  it is recommended] to put environment variables in ##Info.plist##. To edit this file, find your ##Emacs.app## where you installed it or in ##/Applications##. This dir may be translated to your language, when you use the Finder. After right click ##Emacs.app## choose /Show Package Contents/. Open the folder ##Contents## to find ##Info.plist##. Open it with Xcode or a text editor of your choice ;-). Find or add the key [https://developer.apple.com/documentation/bundleresources/information_property_list/lsenvironment LSEnvironment]. Add this:

  <key>LSEnvironment</key>
  <dict>
    <key>PATH</key>
    <string>/usr/bin:/bin:...</string>
  </dict>

Save the file. Enter in Terminal:

  /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/Emacs.app/

This will update the Launch Service Database. You need to restart Emacs.

===getenv/setenv variants===

Note that using any of these, PATH and exec-path will not be kept in sync automatically so you will may want set exec-path as well, e.g.:

          (setq exec-path (split-string (getenv "PATH") ":")

For that reason GNU recommend against this approach (see above).  However it has the advantage of being specific to emacs and the user concerned, and entirely within your init file.

You can use getenv / setenv directly:
 In your init file, e.g. ~/.emacs, add

   (if (string-equal "darwin" (symbol-name system-type))
      (setenv "PATH" (concat "/opt/local/bin:/opt/local/sbin:" (getenv "PATH"))))

You can use them to have the same PATH as .bashrc sets

   (if (not (getenv "TERM_PROGRAM"))
       (setenv "PATH"
               (shell-command-to-string "source $HOME/.bashrc && printf $PATH")))

You can use them to have the PATH from the default SHELL

  (if (not (getenv "TERM_PROGRAM"))
      (let ((path (shell-command-to-string
              "$SHELL -cl \"printf %s \\\"\\\$PATH\\\"\"")))
        (setenv "PATH" path)))

== Keyboard Handling and European Characters ==

Some useful resources: http://en.wikipedia.org/wiki/Keyboard_layout &nbsp;&nbsp;&nbsp; http://www.petermaurer.de/nasi.php?section=keycodes

I have tried outlining 3 basic options for European users in a blog post/video [[http://blog.enqueue.eu/emacs_mac_2 here]]. I do not have a clue about Asian character input, though. Open to comment.

== Map the ALT and the META key close to a "normal" Unix behavior ==

To map the the *left alt key with META* and the *right alt key with ALT*, on the Mac OS X version of GNU Emacs, I use:

    (setq mac-option-key-is-meta t)
    (setq mac-right-option-modifier nil)

It should do the job for the behavior you expect. -- jbcarre

Note: I just looked for a very long time trying to get my mac to use option anything and not get greek characters.  I've always like it bound to <super> instead I was getting opt-d => ∂ and ∫ for opt-b.  Setting the mac-right-option-modifier to nil keeps doing composition.  What fixed this for me was setting the options modifier to super like I was hoping for and now all is great on my mac.

     (setq mac-option-modifier 'super)

-- Cheers MSavoie

== Best Practice ==

Inform all Mac apps of the full PATH, no matter how they are launched.

https://gist.github.com/mcandre/7235205

== Questions ==

* Can not set default window position and size by  ./Emacs.app/Contents/MacOS/Emacs -q -g 400x400 or org.gnu.Emacs.plist. Is there another way to set default window size except from .emacs?

[new:AlpAker:2011-05-23 19:29 UTC]

Not without recompiling, unfortunately.  The NextStep (i.e., OS X) port explicitly disregards any geometry parameters that appear among the command line arguments (look at the the definition of `command-line-ns-option-alist' in lisp/startup.el).  It *should* read org.gnu.Emacs.plist, but the implementation of that is incomplete, so as you've found out, that method doesn't work either.  Your only options are to modify startup.el to pass size parameters to the initial make-frame command, or to change the values of ##DEFAULT_ROWS## and ##DEFAULT_COLS## in src/frame.c.  In either case, you'll have to rebuild the application.  -- AlpAker

[new]
* I'm missing an "emacs" binary, to execute from the command line, from Emacs.app. It's expected by some Makefiles, for instance. Does anyone know how to create or fake one? -- ThomasKappler

The executable binary is already there: Emacs.app/Contents/MacOS/Emacs. -- UntitledApple

[new]
* Is there a way to get visual beep to NOT be a 100x100 black square
in the middle of the window? That's beyond unusable and completely
preventing me from upgrading from 22 to 23. -- RyanDavis

* These build directions fail under 10.6.1 (Snow Leopard).  Does anyone know when a fix is planned?

** Snow Leopard (10.6.1) has to be 32bit. 

        $ CC='gcc -arch i386' ./configure --with-ns
        $ make bootstrap

** The above still blows up for me on 10.6.1, trying to compile 23.1, as does trying to just run 'make' after the configure step.

[new]
I did not encounter the PATH issue w/ <nowiki>MacPorts</nowiki>' emacs-app on Lion --[[gerber]] 2011/12/07
----
CategoryPorts