{"id":15062987,"url":"https://github.com/jimeh/build-emacs-for-macos","last_synced_at":"2025-05-15T15:06:42.882Z","repository":{"id":1842140,"uuid":"2766668","full_name":"jimeh/build-emacs-for-macos","owner":"jimeh","description":"Somewhat hacky script to automate building of Emac.app on macOS.","archived":false,"fork":false,"pushed_at":"2025-04-04T07:48:49.000Z","size":748,"stargazers_count":526,"open_issues_count":9,"forks_count":55,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-13T13:19:36.628Z","etag":null,"topics":["emacs","hacktoberfest","macos"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"disqus/disqus-wordpress","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimeh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-11-13T14:30:21.000Z","updated_at":"2025-05-06T17:41:08.000Z","dependencies_parsed_at":"2024-06-18T21:12:05.468Z","dependency_job_id":"f7abd5f3-2c96-4cc4-b516-23d9cbfdae2d","html_url":"https://github.com/jimeh/build-emacs-for-macos","commit_stats":{"total_commits":309,"total_committers":10,"mean_commits":30.9,"dds":0.0744336569579288,"last_synced_commit":"f7b2baa3636edd1d547e9f70cf783d8114350047"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimeh%2Fbuild-emacs-for-macos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimeh%2Fbuild-emacs-for-macos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimeh%2Fbuild-emacs-for-macos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimeh%2Fbuild-emacs-for-macos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimeh","download_url":"https://codeload.github.com/jimeh/build-emacs-for-macos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364270,"owners_count":22058878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","hacktoberfest","macos"],"created_at":"2024-09-24T23:49:36.990Z","updated_at":"2025-05-15T15:06:42.860Z","avatar_url":"https://github.com/jimeh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# build-emacs-for-macos\n\nMy personal hacked together script for building a completely self-contained\nEmacs.app application on macOS, from any git branch, tag, or ref. With support\nfor native-compilation.\n\nUse this script at your own risk.\n\n## Why?\n\n- To use new features available from master or branches, which have not made it\n  into a official stable release yet.\n- Homebrew builds of Emacs are not self-contained applications, making it very\n  difficult when doing HEAD builds and you need to rollback to a earlier\n  version.\n- Both Homebrew HEAD builds, and nightly builds from emacsformacosx.com are\n  built from the `master` branch. This script allows you to choose any branch,\n  tag, or git ref you want.\n\n## Binary Builds\n\nNightly and stable binary builds produced with this build script are available\nfrom [jimeh/emacs-builds](https://github.com/jimeh/emacs-builds).\n\n## Limitations\n\nThe build produced does have some limitations:\n\n- It is not a universal application. The CPU architecture of the built\n  application will be that of the machine it was built on.\n- The minimum required macOS version of the built application will be the same\n  as that of the machine it was built on.\n- The application is not signed automatically, but the CLI tool used to sign the\n  nightly builds is available. Run `go run ./cmd/emacs-builder package --help`\n  for details. More detailed instructions will come soon.\n\n## Requirements\n\nRequired with both Nix and Homebrew approaches:\n\n- [Xcode](https://apps.apple.com/gb/app/xcode/id497799835?mt=12)\n\n### Nix\n\nThe [Nix](https://nixos.org/) package manager is the preferred and most reliable\nway to install all dependencies required to build Emacs, by way of a Nix flake\nincluded in the project root.\n\nTo install all required dependencies within the nix shell, run:\n\n```\nnix develop --command make bootstrap\n```\n\n### Homebrew\n\nIf you do not have Nix installed, then the alternative way to manage and install\nbuild-time dependencies is via [Homebrew](https://brew.sh/).\n\nRuby 3.3.x or later is also needed to execute the build script. Earlier versions\nmay work, but are untested. Simplest way to install a recent Ruby version is via\nHomebrew:\n\n```\nbrew install ruby\n```\n\nAnd finally, to install all built-time dependencies, run:\n\n```\nmake bootstrap\n```\n\n## Status\n\nAs of writing (2024-11-30) it works for me on my machine and for the nightly\nbuilds in [jimeh/emacs-builds](https://github.com/jimeh/emacs-builds). Your luck\nmay vary.\n\nI have successfully built:\n\n- `emacs-29.4` release tag.\n- `emacs-30.0.92` pretest tag.\n- `master` branch (Emacs 31.x).\n\nFor reference, my machine is:\n\n- 14-inch MacBook Pro (2023), Apple M3 Max (16-cores)\n- macOS Sonoma 15.1.1 (24B91)\n- Xcode 16.1 (16B40)\n\nThe [nightly builds](https://github.com/jimeh/emacs-builds) are built with\nGitHub Actions on GitHub-hosted runners, using `macos-13` for Intel builds, and\n`macos-14` for Apple Silicon builds. The build environment is managed with Nix,\nand targets the macOS 11 SDK.\n\n## Usage\n\n### Nix\n\nEnsure [Flakes](https://nixos.wiki/wiki/Flakes) are enabled, and enter the flake\ndevelopment environment with `nix develop`. Within this environment, you can\nexecute the `./build-emacs-for-macos --help` to get started.\n\nOr you can run the build script via `nix develop`:\n\n```\nnix develop --command ./build-emacs-for-macos --help\n```\n\nThe Nix environment defaults to targeting the macOS 11 SDK, which makes Emacs\nbuilds compatible with macOS 11.3 or later. You can easily target later macOS\nSDKs. Versions 11 to 15 are available. For example, to target the macOS 12 SDK,\nrun `nix develop .#macos12`\n\n### Homebrew\n\nRun `make boostrap` to ensure all Ruby and Homebrew dependencies are installed.\n\n### Build Script\n\n```\nUsage: ./build-emacs-for-macos [options] \u003cbranch/tag/sha\u003e\n\nBranch, tag, and SHA are from the emacs-mirror/emacs/emacs Github repo,\navailable here: https://github.com/emacs-mirror/emacs\n\nOptions:\n        --info                       Print environment info and detected library paths, then exit\n        --preview                    Print preview details about build and exit.\n    -j, --parallel COUNT             Compile using COUNT parallel processes (detected: 16)\n        --git-sha SHA                Override detected git SHA of specified branch allowing builds of old commits\n        --[no-]use-nix               Use Nix instead of Homebrew to find dependencies (default: enabled if IN_NIX_SHELL is set)\n        --[no-]tree-sitter           Enable/disable tree-sitter if supported (default: enabled)\n        --[no-]native-comp           Enable/disable native-comp (default: enabled if supported)\n        --optimize                   Shorthand for --native-march --native-mtune --fomit-frame-pointer (default: disabled)\n        --[no-]native-march          Enable/disable -march=native CFLAG (default: disabled)\n        --[no-]native-mtune          Enable/disable -mtune=native CFLAG (default: disabled)\n        --[no-]fomit-frame-pointer   Enable/disable -fomit-frame-pointer CFLAG (default: disabled)\n        --[no-]native-full-aot       Enable/disable NATIVE_FULL_AOT / Ahead of Time compilation (default: disabled)\n        --[no-]relink-eln-files      Enable/disable re-linking shared libraries in bundled *.eln files (default: enabled)\n        --[no-]rsvg                  Enable/disable SVG image support via librsvg (default: enabled)\n        --[no-]dbus                  Enable/disable dbus support (default: enabled)\n        --[no-]alpha-background      Enable/disable experimental alpha-background patch when building Emacs 30.x - 31.x (default: disabled)\n        --no-frame-refocus           Apply no-frame-refocus patch when building Emacs 27.x - 31.x (default: disabled)\n        --no-titlebar                Apply no-titlebar patch when building Emacs 27.x - 28.x (default: disabled)\n        --[no-]xwidgets              Enable/disable XWidgets when building Emacs 27.x (default: disabled)\n        --[no-]poll                  Apply poll patch (deprecated)\n        --posix-spawn                Apply posix-spawn patch (deprecated)\n    -p, --patch=URL                  Specify a custom patch file or URL to apply to the Emacs source (can be used multiple times)\n        --[no-]fd-setsize SIZE       Set an file descriptor (max open files) limit (default: 10000)\n        --github-src-repo REPO       Specify a GitHub repo to download source tarballs from (default: emacs-mirror/emacs)\n        --[no-]github-auth           Make authenticated GitHub API requests if GITHUB_TOKEN environment variable is set.(default: enabled)\n        --work-dir DIR               Specify a working directory where tarballs, sources, and builds will be stored and worked with\n    -o, --output DIR                 Output directory for finished builds (default: \u003cwork-dir\u003e/builds)\n        --build-name NAME            Override generated build name\n        --dist-include x,y,z         List of extra files to copy from Emacs source into build folder/archive (default: COPYING)\n        --[no-]self-sign             Enable/disable self-signing of Emacs.app (default: enabled)\n        --[no-]archive               Enable/disable creating *.tbz archive (default: enabled)\n        --[no-]archive-keep-build-dir\n                                     Enable/disable keeping source folder for archive (default: disabled)\n        --log-level LEVEL            Build script log level (default: info)\n        --plan FILE                  Follow given plan file, instead of using given git ref/sha\n```\n\nResulting applications are saved to the `builds` directory in a bzip2 compressed\ntarball.\n\nIf you don't want the build process to eat all your CPU cores, pass in a `-j`\nvalue of how many CPU cores you want it to use.\n\nRe-building the same Git SHA again can yield weird results unless you first\ntrash the corresponding directory from the `sources` directory.\n\n### Examples\n\nTo download a tarball of the `master` branch (Emacs 28.x with native-compilation\nas of writing) and build Emacs.app from it:\n\n```\n./build-emacs-for-macos\n```\n\nTo build the stable `emacs-29.4` release git tag run:\n\n```\n./build-emacs-for-macos emacs-29.4\n```\n\nAll sources as downloaded as tarballs from the\n[emacs-mirror](https://github.com/emacs-mirror/emacs) GitHub repository. Hence\nto get a list of tags/branches available to install, simply check said\nrepository.\n\n## Use Emacs.app as `emacs` CLI Tool\n\nBuilds come with a custom `emacs` shell script launcher for use from the command\nline, located next to `emacsclient` in `Emacs.app/Contents/MacOS/bin`.\n\nThe custom `emacs` script makes sure to use the main\n`Emacs.app/Contents/MacOS/Emacs` executable from the correct path, ensuring it\nfinds all the relevant dependencies within the Emacs.app bundle, regardless of\nit it's exposed via `PATH` or symlinked to from elsewhere.\n\nTo use it, simply add `Emacs.app/Contents/MacOS/bin` to your `PATH`. For\nexample, if you place Emacs.app in `/Applications`:\n\n```bash\nif [ -d \"/Applications/Emacs.app/Contents/MacOS/bin\" ]; then\n  export PATH=\"/Applications/Emacs.app/Contents/MacOS/bin:$PATH\"\n  alias emacs=\"emacs -nw\" # Always launch \"emacs\" in terminal mode.\nfi\n```\n\nIf you want `emacs` in your terminal to launch a GUI instance of Emacs, don't\nuse the alias from the above example.\n\n## Native-Comp\n\nThe build script will automatically detect if the source tree being built\nsupports native-compilation, and enable it if available. You can override the\nauto-detection logic to force enable or force disable native-compilation by\npassing `--native-comp` or `--no-native-comp` respectively.\n\nBy default `NATIVE_FULL_AOT` is disabled which ensures a fast build by native\ncompiling as few elisp source files as possible to build Emacs itself. Any\nremaining elisp files will be dynamically compiled in the background the first\ntime they are used.\n\nTo enable native full Ahead-of-Time compilation, pass in the `--native-full-aot`\noption, which will native-compile all of Emacs' elisp at built-time. On my\nmachine it takes around 10 minutes to build Emacs.app with `NATIVE_FULL_AOT`\ndisabled, and around 20-25 minutes with it enabled.\n\n### Configuration\n\n#### Native-Lisp Cache Directory\n\nBy default natively compiled `*.eln` files will be cached in\n`~/.emacs.d/eln-cache/`. If you want to customize that, simply set a new path as\nthe first element of the `native-comp-eln-load-path` variable. The path string\nmust end with a `/`.\n\nBelow is an example which stores all compiled `*.eln` files in `cache/eln-cache`\nwithin your Emacs configuration directory:\n\n```elisp\n(when (boundp 'native-comp-eln-load-path)\n  (setcar native-comp-eln-load-path\n          (expand-file-name \"cache/eln-cache/\" user-emacs-directory)))\n```\n\n#### Compilation Warnings\n\nBy default any warnings encountered during async native compilation will pop up\na warnings buffer. As this tends to happen rather frequently with a lot of\npackages, it can get annoying. You can disable showing these warnings by setting\n`native-comp-async-report-warnings-errors` to `nil`:\n\n```elisp\n(setq native-comp-async-report-warnings-errors nil)\n```\n\n### Issues\n\nPlease see all issues with the\n[`native-comp`](https://github.com/jimeh/build-emacs-for-macos/issues?q=is%3Aissue+is%3Aopen+label%3Anative-comp)\nlabel. It's a good idea if you read through them so you're familiar with the\ntypes of issues and or behavior you can expect.\n\n### Known Good Commits/Builds\n\nA list of known \"good\" commits which produce working builds is tracked in:\n[#6 Known good commits for native-comp](https://github.com/jimeh/build-emacs-for-macos/issues/6)\n\n## Credits\n\n- I've borrowed some ideas from [David Caldwell](https://github.com/caldwell)'s\n  excellent [build-emacs](https://github.com/caldwell/build-emacs) project,\n  which produces all builds for\n  [emacsformacosx.com](https://emacsformacosx.com).\n- Patches applied are pulled from\n  [emacs-plus](https://github.com/d12frosted/homebrew-emacs-plus), which is an\n  excellent Homebrew formula with lots of options not available elsewhere.\n- The following sources were extremely useful in figuring out how get get the\n  `feature/native-comp` branch building on macOS:\n  - https://gist.github.com/mikroskeem/0a5c909c1880408adf732ceba6d3f9ab#1-gcc-with-libgccjit-enabled\n  - https://github.com/shshkn/emacs.d/blob/master/docs/nativecomp.md\n  - https://gist.github.com/AllenDang/f019593e65572a8e0aefc96058a2d23e\n\n## Internals\n\nThe script downloads the source code as a gzipped tar archive from the\n[GitHub mirror](https://github.com/emacs-mirror/emacs) repository, as it makes\nit very easy to get a tarball of any given git reference.\n\nIt then runs `./configure` with a various options, including copying various\ndynamic libraries into the application itself. So the built application should\nin theory run on a macOS install that does not have Homebrew, or does not have\nthe relevant Homebrew formulas installed.\n\nCode quality of the script itself, is well, non-existent. The build script\nstarted life a super-quick hack back in 2013, and now it's even more of a dirty\nhack. I might clean it up and add unit tests if I end up relying on this script\nfor a prolonged period of time. For now I plan to use it at least until\nnative-comp lands in a stable Emacs release for macOS.\n\n## License\n\n[CC0 1.0 Universal](http://creativecommons.org/publicdomain/zero/1.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimeh%2Fbuild-emacs-for-macos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimeh%2Fbuild-emacs-for-macos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimeh%2Fbuild-emacs-for-macos/lists"}