:PROPERTIES: :ID: ec037164-cec0-4b3a-b942-a2b3a34a28ca :END: #+begin_html

Emacs Plus

** About :PROPERTIES: :ID: 94ea0bf6-320c-4aab-9e7a-6902e1f69f15 :END:

#+begin_html #+end_html

Emacs Plus is [[https://www.gnu.org/software/emacs/emacs.html][→ GNU Emacs]] formulae for macOS [[https://brew.sh][→ Homebrew]] package manager. It offers a wide rage of extra functionality over regular [[https://formulae.brew.sh/formula/emacs#default][→ Emacs]] package. Emacs Plus intent is to give the most of 'plus' stuff by default, leaving only controversial options as opt-in. Please refer to [[#options][→ Options]] section for more information.

#+begin_src bash $ brew tap d12frosted/emacs-plus $ brew install emacs-plus [options] # install the latest release (Emacs 27) $ brew install [email protected] [options] # install Emacs 26 $ brew install [email protected] [options] # install Emacs 27 $ brew install [email protected] [options] # install Emacs 28 #+end_src

Feel free to open an issue or contact me via email if you face any issues, questions or feature requests. I love pull requests, so do send them. You might want to check [[docs/development-guidelines.org][→ Development guidelines]] to have better understanding on how to contribute.

** Table of Contents :TOC_3: :PROPERTIES: :ID: fe0f0130-b518-4b40-b440-5564066f5a88 :END:

• [[#about][About]]
• [[#install][Install]]
• [[#reinstall][Reinstall]]
• [[#emacs-26-options][Emacs 26 options]]
• [[#emacs-27-and-emacs-28-options][Emacs 27 and Emacs 28 options]]
  • [[#no-titlebar][No Titlebar]]
  • [[#xwidgets-webkit][Xwidgets (webkit)]]
  • [[#system-appearance-change][System appearance change]]
  • [[#gccemacs][gccemacs]]
• [[#icons][Icons]]
• [[#emacs-configuration][Emacs configuration]]
• [[#known-issues][Known Issues]]
  • [[#emacs-dependency-in-other-formulas][=emacs= dependency in other formulas]]
• [[#screenshots][Screenshots]]
• [[#acknowledgements][Acknowledgements]]

** Install :PROPERTIES: :ID: 5a91bfc6-30cd-4740-9aea-59b25a5a9e33 :END:

Emacs Plus contains separate formulas for different Emacs versions:

• =emacs-plus= install current release version (Emacs 27);

• [email protected]= install Emacs 26, previous release version;

• [email protected]= install Emacs 27, current release version;

• [email protected]= install Emacs 28, development version.

  #+begin_src bash $ brew tap d12frosted/emacs-plus $ brew install emacs-plus [options] # install the latest release (Emacs 27) $ brew install [email protected] [options] # install Emacs 26 $ brew install [email protected] [options] # install Emacs 27 $ brew install [email protected] [options] # install Emacs 28 #+end_src

By default (without any addition options) this formula install Cocoa version of Emacs with support of =gnutls=, =imagemagick=, =librsvg=, =libxml2=, dynamic modules and multicolor fonts. Please see the list of available options to disable any bit of default behaviour or add even more stuff.

** Reinstall :PROPERTIES: :ID: 1d1501a1-21c7-4a98-ae12-51ee049ae175 :END:

If you wish to reinstall =emacs-plus= with you should not use =reinstall= command of =brew= (not related to this formula, it's a general advice). Instead, you should =uninstall= a package and then =install= it with desired options.

Avoid =reinstall= even if you want to =reinstall= with the same set of options, otherwise you will likely to get compilation errors! For example, [[https://github.com/d12frosted/homebrew-emacs-plus/issues/218][#218]] and [[https://github.com/d12frosted/homebrew-emacs-plus/issues/321][#321]].

In short, =brew= doesn't really support options. They break time to time ([[https://github.com/Homebrew/brew/issues/4793][brew#4793]], [[https://github.com/Homebrew/brew/issues/7397][brew#7397]], [[https://github.com/Homebrew/brew/issues/7498][brew#7498]] to show a few).

#+BEGIN_SRC bash $ brew uninstall emacs-plus $ brew install emacs-plus [options] #+END_SRC

** Emacs 26 options :PROPERTIES: :ID: c3fb3ff5-0c6e-4588-a61f-771bee738edd :END:

Emacs 26 comes without any available options due to [[https://github.com/d12frosted/homebrew-emacs-plus/issues/195][→ #195]].

** Emacs 27 and Emacs 28 options :PROPERTIES: :ID: 231811b8-e149-41b1-9d6a-d508a3512c87 :END:

| Option | Description | |---------------------------+------------------------------------------------------------------------------| | =--with-ctags= | don't remove the ctags executable that Emacs provides | | =--with-dbus= | build with dbus support | | =--with-debug= | build with debug symbols and debugger friendly optimizations | | =--with-mailutils= | build with mailutils support | | =--with-no-frame-refocus= | disables frame re-focus (ie. closing one frame does not refocus another one) | | =--with-no-titlebar= | build [[#no-titlebar][→ without titlebar]] | | =--with-x11= | build with x11 support | | =--with-xwidgets= | build [[#xwidgets-webkit][→ with xwidgets]] support | | =--without-cocoa= | build a non-Cocoa version of Emacs (terminal only) | | =--without-imagemagick= | build without =imagemagick= support | | =--HEAD= | build from =emacs-27= branch (only for [email protected]=) | | =--with-native-comp= | build from =native-comp= branch aka [[#gccemacs][→ gccemacs]] (only for [email protected]=) |

By default =emacs-plus= builds the Cocoa version of Emacs.

=emacs-plus= unconditionally enables support for =gnutls=, =librsvg=, =libxml2=, =little-cms2= and dynamic modules.

*** No Titlebar :PROPERTIES: :ID: ec120d87-5570-4259-a434-5909129b7b7c :END:

This patch is enabled with the =--with-no-titlebar= option. It is meant for use with window tiling applications like [[https://github.com/koekeishiya/yabai][→ yabai]], [[https://github.com/koekeishiya/chunkwm][→ chunkwm]] or [[https://github.com/ianyh/Amethyst][→ amethyst]] so that the titlebar you will never need to click on won't take up screen real estate. If you see gaps between your emacs frames and other windows, try this:

#+BEGIN_SRC emacs-lisp (setq frame-resize-pixelwise t) #+END_SRC

*** Xwidgets (webkit) :PROPERTIES: :ID: 6cd905b9-dd43-4888-b717-c5abbb08a25d :END:

Browse the web in Emacs as in modern browser.

The original [[https://www.emacswiki.org/emacs/EmacsXWidgets][→ Emacs xwidgets]] builds and works on macOS however must be used with X11 and hence not practical option on macOS. This version enables =xwidgets= on native macOS Cocoa via embedding a native webkit window.

More details can be seen here [[https://github.com/veshboo/emacs][→ Veshboo's emacs branch]].

*** System appearance change :PROPERTIES: :ID: 8cef837f-359b-4528-ac0e-0977e1bf37f3 :END:

This patch is enabled by default and can't be disabled. It adds a hook, =ns-system-appearance-change-functions=, that is called once the system appearance is changed. Functions added to this hook will be called with one argument, a symbol that is either =light= or =dark=. This mainly allows loading a different theme to better match the system appearance.

#+begin_src emacs-lisp (defun my/apply-theme (appearance) "Load theme, taking current system APPEARANCE into consideration." (mapc #'disable-theme custom-enabled-themes) (pcase appearance ('light (load-theme 'tango t)) ('dark (load-theme 'tango-dark t))))

(add-hook 'ns-system-appearance-change-functions #'my/apply-theme) #+end_src

Note that this hook is also run once when Emacs is initialized, so simply adding the above to your =init.el= will allow matching the system appearance upon startup. You can also determine what the current system appearance is by inspecting the value of the =ns-system-appearance= variable.

The hook is NOT run in TTY Emacs sessions.

*** gccemacs :PROPERTIES: :ID: 7fab3512-2894-42b8-ad90-74298e4ff212 :END:

#+begin_quote gccemacs is a modified Emacs capable of compiling and running Emacs Lisp as native code in form of re-loadable elf files. As the name suggests this is achieved blending together Emacs and the gcc infrastructure.

[[https://akrl.sdf.org/gccemacs.html][→ Andrea Corallo]] #+end_quote

While =gccemacs= gives performance boost in many scenarios, this feature is still experimental and might require time and effort from your side for it to work! Use at our own risk :)

Please see official [[https://akrl.sdf.org/gccemacs.html][→ gccemacs documentation]] for more information.

Knows issues:

• =ld: library not found for -lSystem=. This only happens on older versions of =gcc= installed by Homebrew. Please execute =$ brew reinstall gcc libgccjit= to resolve this issue.
• Errors during compilation of your =init.el=. Try running Emacs with =-Q= option and give it some time to compile everything (maybe run =M-x= to force compilation) - you shall see buffer =Async-native-compile-log= in the list of buffers.

** Icons :PROPERTIES: :ID: 2d6e4b1c-b60a-4331-ab11-beb95cd7e98c :END:

| Option | Author | Image | URL | |-----------------------------------------------+----------------------------+------------------------------------------------+---------| | =--with-EmacsIcon1-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon1_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon2-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon2_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon3-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon3_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon4-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon4_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon5-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon5_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon6-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon6_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon7-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon7_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon8-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon8_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-EmacsIcon9-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/EmacsIcon9_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-cacodemon-icon= | [[https://gitlab.com/wildwestrom][→ Christian Westrom]] | [[/icons/cacodemon_128.png]] | [[https://gitlab.com/wildwestrom/emacs-doom-icon][→ Link]] | | =--with-elrumo1-icon= | [[https://github.com/elrumo][→ Elias]] | [[/icons/elrumo1_128.png]] | [[https://github.com/d12frosted/homebrew-emacs-plus/issues/303#issuecomment-763928162][→ Link]] | | =--with-elrumo2-icon= | [[https://github.com/elrumo][→ Elias]] | [[/icons/elrumo2_128.png]] | [[https://github.com/d12frosted/homebrew-emacs-plus/issues/303#issuecomment-763928162][→ Link]] | | =--with-emacs-card-blue-deep-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/emacs-card-blue-deep_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-emacs-card-british-racing-green-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/emacs-card-british-racing-green_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-emacs-card-carmine-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/emacs-card-carmine_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-emacs-card-green-icon= | [[https://github.com/jasonm23][→ Jason Milkins]] | [[/icons/emacs-card-green_128.png]] | [[https://github.com/emacsfodder/emacs-icons-project][→ Link]] | | =--with-gnu-head-icon= | [[https://github.com/aurium][→ Aurélio A. Heckert]] | [[/icons/gnu-head_128.png]] | [[https://www.gnu.org/graphics/heckert_gnu.html][→ Link]] | | =--with-modern-alecive-flatwoken-icon= | [[https://www.iconarchive.com/artist/alecive.html][→ Alessandro Roncone]] | [[/icons/modern-alecive-flatwoken_128.png]] | [[https://www.iconarchive.com/show/flatwoken-icons-by-alecive.html][→ Link]] | | =--with-modern-asingh4242-icon= | [[https://imgur.com/user/asingh4242][→ Asingh4242]] | [[/icons/modern-asingh4242_128.png]] | [[https://imgur.com/YGxjLZw][→ Link]] | | =--with-modern-azhilin-icon= | Andrew Zhilin | [[/icons/modern-azhilin_128.png]] | [[https://commons.wikimedia.org/wiki/File:Emacs-icon-48x48.png][→ Link]] | | =--with-modern-bananxan-icon= | [[https://www.deviantart.com/bananxan][→ BananXan]] | [[/icons/modern-bananxan_128.png]] | [[https://www.deviantart.com/bananxan/art/Emacs-icon-207744728][→ Link]] | | =--with-modern-black-dragon-icon= | [[https://www.cleanpng.com/users/@osike.html][→ Osike]] | [[/icons/modern-black-dragon_128.png]] | [[https://www.cleanpng.com/png-spacemacs-computer-software-command-line-interface-3947037][→ Link]] | | =--with-modern-black-gnu-head-icon= | [[http://www.aha-soft.com][→ Aha-Soft]] | [[/icons/modern-black-gnu-head_128.png]] | [[https://www.iconfinder.com/iconsets/flat-round-system][→ Link]] | | =--with-modern-black-variant-icon= | [[https://www.deviantart.com/blackvariant/about][→ BlackVariant]] | [[/icons/modern-black-variant.png]] | [[https://www.deviantart.com/blackvariant][→ Link]] | | =--with-modern-bokehlicia-captiva-icon= | [[https://www.deviantart.com/bokehlicia][→ Bokehlicia]] | [[/icons/modern-bokehlicia-captiva_128.png]] | [[https://www.iconarchive.com/show/captiva-icons-by-bokehlicia/emacs-icon.html][→ Link]] | | =--with-modern-cg433n-icon= | [[https://github.com/cg433n][→ cg433n]] | [[/icons/modern-cg433n.png]] | [[https://github.com/cg433n/emacs-mac-icon][→ Link]] | | =--with-modern-doom-icon= | [[http://eccentric-j.com/][→ Eccentric J]] | [[/icons/modern-doom_128.png]] | [[https://github.com/eccentric-j/doom-icon][→ Link]] | | =--with-modern-doom3-icon= | [[http://eccentric-j.com/][→ Eccentric J]] | [[/icons/modern-doom3_128.png]] | [[https://github.com/eccentric-j/doom-icon][→ Link]] | | =--with-modern-icon= | Unknown | [[/icons/modern_128.png]] | Unknown | | =--with-modern-mzaplotnik-icon= | [[https://commons.wikimedia.org/wiki/User:MZaplotnik][→ Matjaz Zaplotnik]] | [[/icons/modern-mzaplotnik_128.png]] | [[https://commons.wikimedia.org/wiki/File:Emacs-icon-48x48.svg][→ Link]] | | =--with-modern-nuvola-icon= | [[https://en.wikipedia.org/wiki/David_Vignoni][→ David Vignoni]] | [[/icons/modern-nuvola.png]] | [[https://commons.wikimedia.org/wiki/File:Nuvola_apps_emacs_vector.svg][→ Link]] | | =--with-modern-orange-icon= | [[https://github.com/VentGrey][→ Omar Jair Purata Funes]] | [[/icons/modern-orange_128.png]] | [[https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/issues/1742][→ Link]] | | =--with-modern-paper-icon= | [[https://github.com/snwh][→ Sam Hewitt]] | [[/icons/modern-paper_128.png]] | [[https://github.com/snwh/paper-icon-theme/blob/master/Paper/512x512/apps/emacs.png][→ Link]] | | =--with-modern-papirus-icon= | [[https://github.com/PapirusDevelopmentTeam][→ Papirus Development Team]] | [[/icons/modern-papirus.png]] | [[https://github.com/PapirusDevelopmentTeam/papirus-icon-theme][→ Link]] | | =--with-modern-pen-3d-icon= | Unknown | [[/icons/modern-pen-3d_128.png]] | [[https://download-mirror.savannah.gnu.org/releases/emacs/icons][→ Link]] | | =--with-modern-pen-black-icon= | [[https://gitlab.com/csantosb][→ Cayetano Santos]] | [[/icons/modern-pen-black_128.png]] | [[https://gitlab.com/uploads/-/system/project/avatar/11430322/emacs_icon_132408.png][→ Link]] | | =--with-modern-pen-icon= | [[https://github.com/nanasess][→ Kentaro Ohkouchi]] | [[/icons/modern-pen.png]] | [[https://github.com/nanasess/EmacsIconCollections][→ Link]] | | =--with-modern-pen-lds56-icon= | [[http://lds56.github.io/about][→ lds56]] | [[/icons/modern-pen-lds56_128.png]] | [[http://lds56.github.io/notes/emacs-icon-redesigned][→ Link]] | | =--with-modern-purple-flat-icon= | [[https://jeremiahfoster.com][→ Jeremiah Foster]] | [[/icons/modern-purple-flat_128.png]] | [[https://icon-icons.com/icon/emacs/103962][→ Link]] | | =--with-modern-sexy-v1-icon= | [[https://emacs.sexy][→ Emacs is Sexy]] | [[/icons/modern-sexy-v1.png]] | [[https://emacs.sexy][→ Link]] | | =--with-modern-sexy-v2-icon= | [[https://emacs.sexy][→ Emacs is Sexy]] | [[/icons/modern-sexy-v2.png]] | [[https://emacs.sexy][→ Link]] | | =--with-modern-sjrmanning-icon= | [[https://github.com/sjrmanning][→ sjrmannings]] | [[/icons/modern-sjrmanning.png]] | [[https://github.com/sjrmanning/emacs-icon][→ Link]] | | =--with-modern-vscode-icon= | [[https://github.com/vdegenne][→ Valentin Degenne]] | [[/icons/modern-vscode_128.png]] | [[https://github.com/VSCodeEmacs/Emacs][→ Link]] | | =--with-modern-yellow-icon= | Unknown | [[/icons/modern-yellow_128.png]] | [[http://getdrawings.com/emacs-icon#emacs-icon-75.png][→ Link]] | | =--with-retro-emacs-logo-icon= | [[https://www.ee.ryerson.ca/~elf/][→ Luis Fernandes]] | [[/icons/retro-emacs-logo_128.png]] | [[https://en.m.wikipedia.org/wiki/File:Emacs-logo.svg][→ Link]] | | =--with-retro-gnu-meditate-levitate-icon= | Nevrax Design Team | [[/icons/retro-gnu-meditate-levitate_128.png]] | [[https://www.gnu.org/graphics/meditate.en.html][→ Link]] | | =--with-retro-sink-bw-icon= | Unknown | [[/icons/retro-sink-bw.png]] | [[https://www.teuton.org/~ejm/emacsicon/][→ Link]] | | =--with-retro-sink-icon= | [[https://www.teuton.org/~ejm/][→ Erik Mugele]] | [[/icons/retro-sink.png]] | [[https://www.teuton.org/~ejm/emacsicon/][→ Link]] | | =--with-spacemacs-icon= | [[https://github.com/nashamri][→ Nasser Alshammari]] | [[/icons/spacemacs_128.png]] | [[https://github.com/nashamri/spacemacs-logo][→ Link]] |

** Emacs configuration :PROPERTIES: :ID: 9cd35d94-be09-408d-8f2b-99510f163cfb :END:

Emacs is a journey. And for some of you these projects might be inspiring.

• [[https://github.com/purcell/emacs.d][→ Steve Purcell's .emacs.d]]
• [[https://github.com/syl20bnr/spacemacs/][→ Spacemacs]]
• [[https://github.com/hlissner/doom-emacs][→ doom-emacs]]
• [[https://github.com/bbatsov/prelude][→ Prelude]]

** Known Issues :PROPERTIES: :ID: a77b29d2-548b-48db-bad3-677269970bdd :END:

Please checkout [[https://github.com/d12frosted/homebrew-emacs-plus/issues][→ Issues]] page for a list of all known issues. But here are several you should be aware of.

*** =emacs= dependency in other formulas :PROPERTIES: :ID: 85ede619-c294-4c9e-985b-4312aa64baf5 :END:

In some cases (like when installing =cask=) regular =emacs= package will be required. In such cases you might want to install all dependencies manually (except for =emacs=) and then install desired package with =--ignore-dependencies= option.

#+BEGIN_SRC bash $ brew install cask --ignore-dependencies #+END_SRC

** Screenshots :PROPERTIES: :ID: 17fd372f-d33c-440d-96b0-f251c01b1190 :END:

#+BEGIN_HTML

#+BEGIN_HTML

** Acknowledgements :PROPERTIES: :ID: 86cfc483-d4f1-4f56-9304-b5df5a10b875 :END:

Many thanks to all [[https://github.com/d12frosted/homebrew-emacs-plus/graphs/contributors][→ contributors]], issue reporters and bottle providers ([[https://github.com/wadkar][→ Sudarshan Wadkar]], [[https://github.com/jonhermansen][→ Jon Hermansen]]).

Special thanks to patrons [[https://www.patreon.com/d12frosted][supporting]] existence of this project:

• [[https://github.com/jidicula][→ Johanan Idicula]]