Using doom-emacs in Android Emacs

In early 2023, the upcoming Emacs 30.1 release included support for Android GUI. This means that besides desktop, there will also be a native Emacs experience on mobile. (Of course, due to its own restrictions, iOS will not never support Emacs in the future.)

Unlike regular Android apps, just installing the APK is far from enough to use Emacs well on Android; additional configuration is required.

Moreover, since the configuration of doom-emacs involves calling Emacs itself, and the Android system does not provide a ready-made emacs executable command, the configuration is not as smooth as on desktop. Here I share my configuration experience, hoping to help some people.

Special thanks to oldosfan, the main contributor to the Android Port, who has been of great help to me in configuring doom-emacs on Android Emacs.

1. Installing Android Emacs

The best way is to install specific versions of Emacs and Termux, sharing the same sharedUserId manifest attribute and signature, meaning they can access each other's data folders (/data/data/org.gnu.emacs/ and /data/data/com.termux/), allowing Emacs to run applications installed through Termux.

Emacs and termux must be installed in a specific order and version. If installed previously, please uninstall first to avoid sharedUserId or signature conflicts.
First, install a specific version of Termux from Android ports for GNU Emacs - Browse /termux at SourceForge.net. Do not open Termux after installing.
Then, choose a suitable version of Emacs to install from the same website.
- 👎 The version from F-Droid is not recommended because:
  - It's not the latest version: missing bug fixes and new features.
  - It lacks many dependency packages: GnuTLS, image libraries, tree-sitter
- The main selection criteria are Android system version and chip CPU architecture. For example, emacs-30.0.50-29-arm64-v8a.apk is suitable for devices running Android 10.0 or higher on aarch64, a common choice. If the installed version does not match, it will not work properly.
After both are installed, open Termux and execute the following command to install and update all applications.
```
pkg update && pkg upgrade
```

Open Emacs and add to ~/.emacs.d/early-init.el:

(when (string-equal system-type "android")
  ;; Add Termux binaries to PATH environment
  (let ((termuxpath "/data/data/com.termux/files/usr/bin"))
    (setenv "PATH" (concat (getenv "PATH") ":" termuxpath))
    (setq exec-path (append exec-path (list termuxpath)))))

This code binds Emacs with the Termux file system, allowing Emacs to access programs installed through Termux.
🤔 The official documentation also configures the LD_LIBRARY_PATH environment variable. However, configuring it causes problems running mpv in Emacs, and not configuring it has not shown problems so far. To be observed.

Restart Emacs to apply the configuration. If you have already installed git in Termux, you can try executing (executable-find "git") in Emacs. If it returns the path to git, the configuration is successful.

2. Using doom-emacs configuration

Because there is no Emacs executable file in Android and the shell path is different, some modifications are necessary for doom install. Please pay attention to distinguish whether the following operations are run in Termux or in Emacs Shell.

Install Git in Termux
```
pkg install git
```

In Termux, git clone doom-emacs to the Emacs main directory

git clone --depth 1 https://github.com/hlissner/doom-emacs /data/data/org.gnu.emacs/files/.emacs.d.doom

In the shell environment of Android Emacs, soft link the emacs executable file:
```
ln -s /data/data/org.gnu.emacs/lib/libandroid-emacs.so /data/data/com.termux/files/usr/bin/emacs
```
- After successful linking, running emacs --version in Android Emacs should show:
  
  emacs –version GNU Emacs 30.0.50 Copyright (C) 2024 Free Software Foundation, Inc. GNU Emacs comes with ABSOLUTELY NO WARRANTY. You may redistribute copies of GNU Emacs under the terms of the GNU General Public License. For more information about these matters, see the file named COPYING.
- Otherwise, when executing doom, it will report an error:
  
  Error: failed to run Emacs with command 'emacs'
  
  Are you sure Emacs is installed and in your $PATH?
Edit .emacs.d.doom/bin/doom, change the Shebang: #!/usr/bin/env sh → #!/system/bin/sh
- hlissner suggests not to modify the doom Shebang and to specify the shell directly when executing the command, like sh ~/.emacs.d/bin/doom install. Unfortunately, due to the cache mechanism, this solution does not work, and it is necessary to modify the doom Shebang. To upgrade doom, use doom upgrade --force and then modify the Shebang again.
Add the contents of ~/.emacs.d/early-init.el to ~/.doom.d/init.el, to add the Termux path to the PATH environment variable when generating the doom env file.
Execute doom install in Android Emacs
- Running doom install in the shell environment of Android Emacs is very slow, consider copying the repos folder from another environment to ~/.emacs.d.doom/.local/straight/repos, then execute doom install. This skips the git clone step and speeds up the process.
- If prompts error ("Failed to run \"git\"; see buffer *straight-process*"), you can try:
  - Checking if the Termux path is added to the PATH in doom's env file
  - Execute commands in eshell, not in shell
  - Execute (setq android-use-exec-loader nil)
After installation, link .emacs.d.doom as .emacs.d. It is recommended not to rename directly, so that changing the path pointed to by .emacs.d in the future can switch configurations for debugging.
Restart, and Emacs should be able to load the doom-emacs configuration. Since the paths and supported features on Android and desktop are not completely consistent, the doom-emacs configuration generally needs to be adjusted. Enjoy your doom-emacs on Android.

3. Update History

[2024-03-09 六] Edit the file from .emacs.d.doom/early-init.el to ~/.doom.d/init.el, to reduce modifications to the doom-emacs repo, thanks to hlissner.
[2024-02-04 日] First draft