emacs-builds/README.md

<p align="center">
  <img width="192px" src="https://github.com/emacs-mirror/emacs/raw/emacs-27.2/etc/images/icons/hicolor/scalable/apps/emacs.svg" alt="Logo">
</p>

<h1 align="center">
  Emacs Builds
</h1>

<p align="center">
  <a href="https://github.com/jimeh/emacs-builds/releases/latest">
    <img alt="GitHub release (latest)" src="https://img.shields.io/github/v/release/jimeh/emacs-builds?style=flat&label=nightly&color=%237F5AB6&logo=GNU%20Emacs&logoColor=white">
  </a>
  <a href="https://github.com/jimeh/emacs-builds/issues">
    <img alt="GitHub issues" src="https://img.shields.io/github/issues-raw/jimeh/emacs-builds?style=flat&logo=github&colorColor=white">
  </a>
  <a href="https://github.com/jimeh/emacs-builds/pulls">
    <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr-raw/jimeh/emacs-builds?style=flat&logo=github&colorColor=white">
  </a>
  <a href="https://github.com/jimeh/emacs-builds/releases">
    <img alt="GitHub all releases" src="https://img.shields.io/github/downloads/jimeh/emacs-builds/total?style=flat&logoColor=white&logo=data%3Aimage%2Fpng%3Bbase64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAEsmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iCiAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgZXhpZjpQaXhlbFhEaW1lbnNpb249IjE0IgogICBleGlmOlBpeGVsWURpbWVuc2lvbj0iMTQiCiAgIGV4aWY6Q29sb3JTcGFjZT0iMSIKICAgdGlmZjpJbWFnZVdpZHRoPSIxNCIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMTQiCiAgIHRpZmY6UmVzb2x1dGlvblVuaXQ9IjIiCiAgIHRpZmY6WFJlc29sdXRpb249IjcyLjAiCiAgIHRpZmY6WVJlc29sdXRpb249IjcyLjAiCiAgIHBob3Rvc2hvcDpDb2xvck1vZGU9IjMiCiAgIHBob3Rvc2hvcDpJQ0NQcm9maWxlPSJzUkdCIElFQzYxOTY2LTIuMSIKICAgeG1wOk1vZGlmeURhdGU9IjIwMjEtMDUtMThUMDE6MjU6NTQrMDE6MDAiCiAgIHhtcDpNZXRhZGF0YURhdGU9IjIwMjEtMDUtMThUMDE6MjU6NTQrMDE6MDAiPgogICA8eG1wTU06SGlzdG9yeT4KICAgIDxyZGY6U2VxPgogICAgIDxyZGY6bGkKICAgICAgc3RFdnQ6YWN0aW9uPSJwcm9kdWNlZCIKICAgICAgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWZmaW5pdHkgRGVzaWduZXIgMS45LjMiCiAgICAgIHN0RXZ0OndoZW49IjIwMjEtMDUtMThUMDE6MjU6NTQrMDE6MDAiLz4KICAgIDwvcmRmOlNlcT4KICAgPC94bXBNTTpIaXN0b3J5PgogIDwvcmRmOkRlc2NyaXB0aW9uPgogPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0iciI%2FPnP7qIwAAAGBaUNDUHNSR0IgSUVDNjE5NjYtMi4xAAAokXWRzytEURTHP2aIGBEWFhaThtWM%2FKiJjTLSUJM0RhlsZp55M2rezOu9N2myVbaKEhu%2FFvwFbJW1UkRKdsqa2KDnPKNGMud27vnc773ndO%2B54IplFc2s7gUtZxnRcMg7G5%2Fz1j5SQwvQzEBCMfWRqakIFe3thionXgWcWpXP%2FWsNiylTgao64WFFNyzhceHIsqU7vCncpmQSi8LHwn5DLih87ejJEj85nC7xh8NGLDoKrmZhb%2FoXJ3%2BxkjE0YXk5Pi1bUH7u47zEk8rNTEvsFO%2FAJEqYEF4mGGOUIH0MyRwkQD89sqJCfu93%2FiR5yVVk1ilisESaDBZ%2BUQtSPSVRFT0lI0vR6f%2FfvprqQH%2BpuicENQ%2B2%2FdIFtRvwuW7b7%2Fu2%2FXkA7ns4y5Xz83sw%2BCr6elnz7ULTKpycl7XkFpyuQfudnjAS35Jb3KWq8HwEjXFovYT6%2BVLPfvY5vIXYinzVBWzvQLecb1r4AjtZZ9JRQIRfAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAhUlEQVQokb3QsQnDMBRF0Y9J6QGylCt7GI%2BRPdJ4BIMXyA4pM0KKk0YCYawogZAHH4Tuvw%2BhiEowY67xarBirfHu68afijjXFvesK8AQEXeMB9KU2HDU2GPDE2P%2BHEzpbkNfe04pP9K8lw7knLa0k69pPpP%2BFyzaWfL%2BqXAvEXFr9K%2F58AJFIbDLRt48DAAAAABJRU5ErkJggg%3D%3D&color=blue&label=total%20downloads">
  </a>
</p>

<p align="center">
  <strong>
    Nightly binary builds of Emacs for macOS as a self-contained Emacs.app,
    with native-compilation.
  </strong>
</p>

## Features

- Self-contained Emacs.app application bundle, with no external dependencies.
- Native-compilation ([gccemacs][]).
- Native JSON parsing via libjansson.
- SVG rendering via librsvg.
- Various image formats are supported via macOS native image APIs.
- Xwidget-webkit support is enabled, allowing access to a embedded WebKit-based
  browser with `M-x xwidget-webkit-browse-url`.
- Native XML parsing via libxml2.
- Dynamic module loading.
- Includes the [fix-window-role][] and [system-appearance][] patches from the
  excellent [emacs-plus][] project.
- Emacs source is fetched from the [emacs-mirror/emacs][] GitHub repository.
- Build creation is transparent and public through the use of GitHub Actions,
  allowing anyone to inspect git commit SHAs, full source code, and exact
  commands used to produce a build. This is especially important right now as
  builds are not yet signed and notarized.
- Uses [build-emacs-for-macos][] to build the self-contained application bundle.

[build-emacs-for-macos]: https://github.com/jimeh/build-emacs-for-macos
[gccemacs]: https://www.emacswiki.org/emacs/GccEmacs
[fix-window-role]:
  https://github.com/d12frosted/homebrew-emacs-plus/blob/master/patches/emacs-28/fix-window-role.patch
[system-appearance]:
  https://github.com/d12frosted/homebrew-emacs-plus/blob/master/patches/emacs-28/system-appearance.patch
[emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus
[emacs-mirror/emacs]: https://github.com/emacs-mirror/emacs

## System Requirements

- Intel-based Mac running macOS 10.15.x or later.

## Downloads

See the [Releases][] page to download latest builds.

Nightly builds of Emacs are for the part just fine, but if you don't like living
too close to the edge, see issue [#7 Known Good Nightly Builds][7] for a list of
recent nightly builds which have been actively used by a living being without
any issues.

[releases]: https://github.com/jimeh/emacs-builds/releases
[7]: https://github.com/jimeh/emacs-builds/issues/7

## Untrusted Application

Currently builds are not signed or notarized, meaning macOS cannot verify
Emacs.app came from a trusted developer, and by default you are not given an
option to trust the app and open it.

Simplest way around this is to right-click (or control-click) on the Emacs app
in Finder and select "Open". You will then be given the same warning as before,
but with a "Open" button now available to trust and open the app. After that you
can open the application like normal without any warnings.

Builds will soon be signed and notarized, progress is tracked in [Issue #1][1].

[1]: https://github.com/jimeh/emacs-builds/issues/1

## Use Emacs.app as `emacs` CLI Tool

As the application bundle is self-contained, the main executable needs to be run
from within the application bundle. This means a simple symlink to
`Emacs.app/Contents/MacOS/Emacs` will not work. Instead the best approach is to
create a shell alias called `emacs` pointing to the right place.

For example, this will expose both `emacs` and `emacsclient`:

```bash
if [ -f "/Applications/Emacs.app/Contents/MacOS/Emacs" ]; then
  export EMACS="/Applications/Emacs.app/Contents/MacOS/Emacs"
  alias emacs="$EMACS -nw"
fi

if [ -f "/Applications/Emacs.app/Contents/MacOS/bin/emacsclient" ]; then
  alias emacsclient="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient"
fi
```

Setting the `EMACS` variable to the binary path seems to be a good idea, as some
tools seem to use it to figure out the path to Emacs' executable, including
[doom-emacs][]' `doom` CLI tool.

[doom-emacs]: https://github.com/hlissner/doom-emacs

## Build Process

Building Emacs is done using the [jimeh/build-emacs-for-macos][] build script,
executed within a GitHub Actions [workflow][]. This is why macOS 10.15.x or
later is required, as it's the oldest version of macOS available in GitHub
Actions.

[jimeh/build-emacs-for-macos]: https://github.com/jimeh/build-emacs-for-macos
[workflow]:
  https://github.com/jimeh/emacs-builds/blob/main/.github/workflows/build.yml

Full history for all builds is available on GitHub Actions [here][actions].

[actions]: https://github.com/jimeh/emacs-builds/actions

Nightly builds are scheduled for 0:00 UTC every night, based on the latest
commit from the `master` branch of the [emacs-mirror/emacs][] repository. This
means a nightly build will only be produced if there have been new commits since
the last nightly build.

[emacs-mirror/emacs]: https://github.com/emacs-mirror/emacs

## Issues / To-Do

Please see [Issues][] for details of things to come, or to report issues.

[issues]: https://github.com/jimeh/emacs-builds/issues