This directory holds installation packages for the Android port of GNU
Emacs. They are automatically compiled from revisions of the Emacs
repository corresponding to the releases whose names they bear.

On account of size constraints, we cannot provide the source code to
any dependencies bundled with these packages in this directory, but
the same may be acquired with the `admin/download-android-deps.sh'
script in the Emacs repository.

Several types of installation packages exist in this directory, each
of which is intended for a combination of Android releases and
architectures. Variants of many of the same packages also exist in
the `termux' directory; these packages are configured to interface
with the Termux Unix package manager, and must be installed anew; you
will be required to uninstall packages from the `termux' directory
before installing any from this, and vice versa. Following is a table
of the packages and the releases and architectures on which they are
to be installed.

emacs-30.1-16-armeabi-v7a.apk - armv7 architecture devices
with Android 4.1 - 6.0.
emacs-30.1-24-armeabi-v7a.apk - armv7 architecture devices
with Android 7.0 or later.
emacs-30.1-21-arm64-v8a.apk - aarch64 architecture devices
with Android 5.0 - 8.0.
emacs-30.1-29-arm64-v8a.apk - aarch64 architecture devices
with Android 10.0 or later.
emacs-30.1-21-mips64.apk - mips64 architecture devices
with Android 5.0 - 8.1 (the
final Android supporting
mips64 devices).
emacs-30.1-21-x86_64.apk - x86_64 architecture devices
with Android 5.0 - 9.0.
emacs-30.1-29-x86_64.apk - x86_64 architecture devices
with Android 10.0 or later.
emacs-30.1-9-mips.apk - mips architecture devices
with Android 2.3 - 8.1 (the
final Android supporting
mips devices).
emacs-30.1-9-x86.apk - i686 architecture devices
with Android 2.3 or later.
emacs-30.1-9-armeabi.apk - armeabi architecture devices
with Android 2.3 or later.
emacs-30.1-8-armeabi.apk - armeabi architecture devices
with Android 2.2.

Always install the package for the CPU architecture used by your
Android system; if you install any other compatible package (such as
the x86 package on an x86_64 system), subprocess execution will fail.


INSTALLATION WITH TERMUX SUPPORT

Termux is a package manager providing ports of Unix free software for
Android systems. Emacs packages configured to interface with Termux
cannot do so if Termux is not signed with Emacs's application signing
keys, and consequently you must install a build of Termux that does
bear such a signature (one of which is provided below).

To install Emacs with Termux support, first remove any existing copy
of Emacs (this will remove all data within Emacs's home directory, so
make a backup beforehand!) and Termux, to avoid signature or user ID
conflicts. Next, install Termux from this source:

https://sourceforge.net/projects/android-ports-for-gnu-emacs/files/termux/termux-app_apt-android-7-release_universal.apk/download

_first_, then install Emacs. Once both packages are installed, open
Termux, and at the shell prompt displayed therein, type:

$ pkg update && pkg upgrade

confirming each of the inquiries made by the dpkg package manager.
Once all applications have been installed and updated, open Emacs, and
save the following code into `early-init.el':

(setenv "PATH" (format "%s:%s" "/data/data/com.termux/files/usr/bin"
(getenv "PATH")))
(push "/data/data/com.termux/files/usr/bin" exec-path)

after which programs installed through Termux will be made accessible
to Emacs.

It is not necessary to configure the likes of LD_LIBRARY_PATH, as
Termux's binaries have appropriately set `rpath' linker directives.

Please bear in mind that Termux (and the copies of Emacs built to use
it) can only be installed on Android 7.0 and later.


FREQUENTLY ANSWERED QUESTIONS

The answers to most questions frequently asked by users of this Emacs
port can be found in the Emacs and/or Lisp Reference manuals that it
is distributed alongside. Nevertheless, a list of very frequently
answered questions has been compiled, for the benefit of individuals
who are unaware of the previously mentioned documentation.

1. Which package do I download?

Probably `emacs-30.1-29-arm64-v8a.apk' or its counterpart in the
`termux' directory. If your phone or tablet runs a 32-bit OS, then
most likely `emacs-30.1-24-armeabi-v7a.apk'.

2. Which version(s) of Emacs do I install, and which do these packages
correspond to?

Packages labeled `emacs-30.1' correspond to GNU Emacs 30.1, which is
(as of 24 Feb 2025) the latest stable release of GNU Emacs.

3. Where do I get help?

help-gnu-emacs@gnu.org.

4. Where do I report bugs/submit patches?

bug-gnu-emacs@gnu.org.

5. How do I access my documents/source code/etc?

Android apps can be granted access to three different kinds of
storage.

The first is the app data directory, which also serves as the app's
Unix home directory, and is only accessible to Emacs itself.

The second is the external storage directory (located at /sdcard),
which Emacs must explicitly request permission to access. This
directory is what shows up as the ``internal storage'' in your file
manager app.

Prior to Android 11, granting Emacs rights to access this directory
can be performed from the Permissions menu in the App Info settings
panel, by enabling the option labeled Storage; after Android 11, the
path to the setting has changed, and must instead be granted from the
Special App Access menu in Settings.

Contrary to several descriptions being circulated online, it is not
necessary to install the Termux variant for access to external
storage. That being said, either application will gain any
permissions granted to the other (of which the right to access
external storage is one) as a consequence of their shared user ID.

The third is storage provided by other applications (Nextcloud, for
example) through the Storage Access Framework--this storage is
extremely slow (thanks in part to Google's botched implementation of
document provider IPC), and is located within subdirectories of
/content/storage. Before any of these directories become available,
you must run `M-x android-request-directory-access', and select the
directory you want from the file selection panel displayed.

Because the /content directory is implemented entirely within Emacs's
own file input/output primitives, subprocess cannot access any files
it contains. If you attempt to create a subprocess inside that
directory, its working directory will actually be set to Emacs's home
directory. This additionally applies to the /assets directory holding
Lisp and ancillary files distributed with Emacs.

Refer to (emacs)Android Filesystem and (emacs)Android Document
Providers within the Emacs manual for more details.

6. Where is my .emacs/.emacs.d/init.el?

~/.emacs, of course.

You cannot copy an Emacs configuration to the so-called internal
storage on your phone and make it immediately available to Emacs.
This is because, being subject to Android's security model, Emacs is
the only app with permission to access its home directory.

Instead, follow the procedures outlined in the previous answer to
grant Emacs access to that internal storage, and copy your
configuration files from there to your home directory.

Android doesn't guarantee that Emacs's home directory will be located
at any predetermined location, but it is normally placed at
/data/data/org.gnu.emacs/files. On systems with multiple users
(Android users, not Unix users), it may instead be located somewhere
within /data/user/ if Emacs is installed for a user other than the
device owner.

7. Where are binaries like emacs, emacsclient, and movemail?

Short answer: ~/../lib.

Long answer: because Android restricts both the locations from where
executable files can be loaded and the names of the executables that
it will extract from installation packages, Emacs files all of its
ancillary executables under names resembling shared libraries. When
Emacs is installed, Android extracts these executables to a private
directory that Emacs symlinks at startup to `lib' within the parent
directory of its home directory. Refer to (elisp)Subprocess Creation
and (emacs)Android Environment for more details.

While the names of these executables are stable (and will be so for
the forseeable future), it is better to use the variables that are
specifically defined to provide their names:
`emacsclient-program-name', `movemail-program-name' and so on, in
place of hard-coded names such as `libemacsclient.so' and
`libmovemail.so'. Following this advice will guarantee that your code
continues to run faithfully in the future and on non-Android systems.

The location of `emacs' is more involved: the `libemacs.so' is
actually a real shared library containing all of the Emacs C code.
This code is not functional until it is linked to a bundle of Java
code implementing the Android filesystem and GUI interfaces, which is
automatically performed by the Android JVM at run-time when you open
Emacs from the app icon.

`libandroid-emacs.so' is a binary that tries to invoke the JVM with
the right arguments for starting Emacs on the command line. While it
is true that Emacs cannot create a display connection when started in
this manner, the greatest difficulty posed by this approach is rather
its reliance on Android internals that are subject to change without
notice. Because of this unfortunate dependency, it does not work
reliably on all versions of Android, and must be revised after each
major change to the OS.

The true solution to this conundrum is to avoid running Emacs inside
itself, obviating the need for that binary in the first place.

8. Where do I get more software? (clang, git, python, etc.)

See (emacs)Android Software. The `termux' directory holds versions of
both Termux and Emacs that share the same user ID and signing key.

9. The on-screen keyboard isn't displayed! You must only use Emacs
with a physical keyboard!

The author of this port does not use a physical keyboard under
Android. He uses AnySoftKeyboard for English input, and Fcitx

https://github.com/fcitx5-android/fcitx5-android/

for CJK input. With that misconception out of the way, there are at
least two reasons for asking this question.

The first is that you may have unthinkingly disabled the menu bar or
tool bar in keeping with an online Emacs introductory text, and now
want to perform operations which are then impossible without a
keyboard. This is a very unwise decision on Android: any operation
performed from a keyboard can also be performed from the menu bar or
tool bar (including M-x, which is Edit -> Execute Command), making the
use of a keyboard unnecessary.

With that in mind, and to save screen space, the keyboard is normally
hidden when the current window has selected a read-only buffer. The
second reason for asking this question is wanting to always display
the on-screen keyboard; to do so, simply customize the option
`touch-screen-display-keyboard' to a non-nil value. (Options ->
Customize Emacs, hint, hint.)

For more details and an in depth explanation of how Emacs treats touch
screen and on-screen-keyboard input, refer to (emacs)Touchscreens,
(emacs)On-Screen Keyboards, (elisp)Misc Events, and (elisp)Touchscreen
Events.

10. My package X that relies on reading raw key events / binding keys
globally doesn't work with an on screen keyboard!

This is because Android input methods rely on directly invoking
Emacs's buffer editing primitives, which is dubbed text conversion.
Emacs tries to implement features such as electric-indent,
electric-pair and Auto-Fill through analyzing the course of their
edits after they take place.

Consequentially, Emacs doesn't receive raw key press events as you
type into the input method, your package doesn't work, and the text
you type is inserted directly into the current buffer in lieu of the
events you meant to send.

You can either fix these packages to disable text conversion through
the variable `overriding-text-conversion-style' or the buffer-local
variable `text-conversion-style', or disable text conversion globally
by setting the first variable.

See (elisp)Misc Events for further elucidations on the subject of text
conversion.

11. Point jumps to the start of the text after I type an opening
paren! (And other problems with IMEs in Text or Prog Mode
derivatives.)

This is probably a bug in your IME. Emacs implements the Android
input method interfaces to the letter, but Android's own
implementation leaves much to be desired.

One extremely common transgression committed by input methods is to
assume that the `getExtractedText' IME request will always reply with
the entire contents of the buffer regardless of the number of
characters the IME requests, which is indeed the case when the editor
is the Android TextView widget. In contrast, Emacs respects the size
specified in the request, in adherence with the documented behavior
for that request.

An additional transgression is assuming that, since the result of that
request is always the entirety of the text buffer's contents, the
caret offset returned by the input method is the position of the
insertion point. In reality, the base of this offset is the start of
the text returned.

Together, these two implementation mistakes result in many problematic
input methods misleading themselves into thinking that point is at the
start of the buffer. After inserting a closing paren as part of their
own electric-pair features, such input methods often try to obtain the
location of the point and move to the last character prior to the
closing paren. But what they think is the position of that character
is actually the very beginning of the buffer.

If the situation illustrated above does not appear consistent with the
behavior you witness from your IME, however, please send a bug report
(with M-x report-emacs-bug.) In that report, mention the name and
version number of the IME you are using.

12. When I type in fundamental mode / a Custom buffer, the input
method goes haywire!

This is a bug in the IME. Input methods don't just settle for
implementing text conversion incorrectly, they sometimes also forget
to implement the `TYPE_NULL' input mode that requires them to behave
as plain keyboard devices.

These bugs typically manifest as no text being inserted (since Emacs
doesn't provide an input connection when text conversion is disabled),
as the Delete key not working, or in any number of other ways. Get a
better input method, and exhort your friends to do the same.

13. How do I display modifier keys in the tool bar?

Enable `modifier-bar-mode' and `tool-bar-mode'. A small secondary
tool bar will be displayed together with the tool bar containing
buttons that read and modify subsequent events with each of the
modifier keys understood by Emacs.

When you tap one of these buttons, Emacs also displays the on-screen
keyboard and momentarily disables text conversion. This enables you
to type key sequences containing modifier keys even in a Text or Prog
Mode buffer where text conversion is enabled.

14. How do I display the tool bar on the bottom of its frame? I want
the buttons and modifier bar to be near my fingers as I type.

Although not specific to the Android port, the implementation of this
feature on non-GTK systems was motivated by one such request from an
Android port user.

Customize `tool-bar-position' to `bottom'.

15. How do I quit? I can't type C-g.

Click the volume down button in rapid succession, which acts as a
regular C-g.

16. How do I open other files in Emacs?

Run `M-x server-start' (or better yet, place it in your initialization
files.)

When you try to open a text file, the system will display a dialog
asking for a program to run. Select Emacs: emacsclient will be called
to open the file in question, or Emacs will be started with that file
as an argument if it's not already running.

17. What is the difference between this app and Emacs from Termux?

This app runs as a native Android GUI program, enabling it to take
advantage of input methods, document provider programs and suchlike,
and its support for touch screen input is superior, with most common
gestures recognized and/or transparently translated into mouse events.

Distributed Lisp and auxiliary files are stored entirely within the
application package itself, avoiding the need to use a separate
package manager to install Emacs updates. These files are also loaded
directly from the app package, and so do not require a time-consuming
extraction procedure every time Emacs is updated before they can be
used.

This app is also capable of employing ported Unix software from Termux
as well; see the top of this file, and moreover supports old Android
releases before 7.0, which Termux does not.

18. What's the difference between the builds provided here and those
offered by F-Droid?

F-Droid's version is an old snapshot of the Android port from
Februrary; although it has witnessed substantial improvement by
comparison with the version from February they previously distributed,
it remains incomplete and will always be absent bug fixes and new
features present in the packages housed here.

Their versions are also missing many of the dependencies packaged
within the builds provided here: GnuTLS, image libraries, tree-sitter,
and so on.

19. Why can't I update from the F-Droid build to this one?

Because Android requires package updates to be signed with the same
key used to sign the existing installation, and F-Droid uses a signing
key distinct from the one included in the Emacs repository.

Back up your configuration and uninstall the F-Droid build prior to
installing any of the packages in this directory.

20. ``Set Default Font'' in the Options menu does not list the
fonts I have installed.

That menu is in truth a vestige from the early days of Emacs's
graphics support, when the only font ``backend'' was X, and programs
could get away with listing merely the fonts common to most X servers.

When invoked under Android, it produces a litany of fonts that are
seldom really present on Android. Fonts should be configured through
Customize or the `set-frame-font' command instead.

21. Glyphs within Microsoft core fonts (Arial, Tahoma, and the like)
are misshapen or blurry.

Antiquated versions of these fonts exploit extensions and
implementation-specific behavior unique to the Microsoft Windows font
scaler that Emacs does not supply, as a result of which various glyph
programs they define go awry as they are executed to fit glyphs to the
pixel grid. The solution is to update them to their latest revisions,
as distributed with recent releases of MS Windows.

In particular, such fonts expect the interpreter to grant them leave
to address nonexistent glyph points. The MS scaler ignores offending
instructions, while Emacs terminates the program entirely.

22. Tool bar buttons are undersized.

Tool bar button margins do not increase to match the display density,
which produces buttons that appear smaller than expected on
high-density output devices, as featured by most Android phones today.
Adjust the variable `tool-bar-button-margin' to compensate.

23. B/W or grayscale displays are not detected, with the result that
colors applied by the likes of font-lock lack contrast.

This entry is relevant on tablets featuring "digital paper" displays,
monochromatic or grayscale displays being virtually unknown elsewhere.

Android not being designed for such applications, the display's visual
class is not reported to programs, and consequently you the user are
responsible for informing Emacs of the display color depth by means of
the variable `android-display-depth'; for a grayscale display, the
optimal value is anywhere between 2 and 8, where greater values
correspond to more supported grays, while the proper value for a
monochrome display is 1.

Though this value controls color allocation choices, the display
capabilities reported to Lisp, and by extension colors selected during
the realization of faces, yet it does not affect font anti-aliasing or
the display of images, as the underlying surface provided to Emacs is
always color, with the driver converting anti-aliased text and color
graphics into grayscale or monochrome data for the glass instead. Its
purpose is rather to enable users to activate the carefully curated
palette for displays wanting in color space or depth.

24. How/where do I obtain the corresponding source code to which I am
entitled under the terms of the GNU GPL?

Type:

M-x describe-variable RET emacs-repository-version RET

within Emacs. Next, download that revision from the Emacs Git
repository at:

https://git.savannah.gnu.org/git/emacs.git

I also retain source code tarballs produced from the repository for
the binaries that are currently present on SourceForge. Please
contact me if you require those.

25. Termux, its add-ons (or Emacs) won't install.

If you have downloaded and installed either the Termux-enabled Emacs,
or Termux itself, from this site, installation of upstream Termux app
packages will fail with a nondescript error message, as their
signature will disagree with those of the packages already installed.

You must either resign the packages you wish to install with the
upstream Emacs signing key:

https://git.savannah.gnu.org/cgit/emacs.git/tree/java/emacs.keystore

or modify Android to disable its draconian signature verification, as
with an XPosed module such as:

https://github.com/LSPosed/CorePatch

26. Your signing keys are public! You clearly aren't concerned with
security.

We realize that our signing keys are available to the public, and it
follows, to potential malefactors. It does not alarm us in the least:
restricting the right to publish upgrades to a software installation
to its publisher contradicts the basic tenets of the Free Software
movement.

If this heavy-handed Android practice commends itself to you, because
you hold so little faith in the soundness of your judgement that you
may be vulnerable to malware impersonating Emacs, we suggest
installing Emacs from F-Droid instead, who, for reasons inexplicable
to us, treat their package signing keys as jealously guarded secrets.

26. Why does Emacs request [insert alarming permission] / why does
Emacs request such a great many permissions?

Of the 150+ permissions declared in its manifest, none are exercised
by default except SYSTEM_ALERT_WINDOW, which is only invoked to
display tooltips and pop-up dialogs while in the background.

These permissions are declared in order that users may not be denied
the option of utilizing the Android APIs they control from Emacs, as
code executing in Emacs cannot receive permissions beyond what is
declared: who is to say that address book or calendar access will not
benefit directory server clients or Org's agenda facilities in the
future?

It is also incorrect to speak of Emacs as requesting all these
permissions on Android 6.0+, inasmuch as new installations of Emacs
are denied most of them and do not acquire the same without express
intervention by the user.

27. Why do two of the 30+ anti-virus providers on VirusTotal pronounce
Emacs malware?

I am not aware why this is, though it could be connected with the
number of permissions that are declared in its manifest. I give you
my word of honor that there is no malware in this repository, and,
that if you compile Emacs from source code, the binaries produced will
also trigger the same anti-virus services.

28. Certain SVG images are blank.

If you are encountering this issue, it is quite probable that it
should be more accurate to say that images embedded in SVGs fail to be
displayed. This is observed with such packages as osm.el, which
employ SVG wrappers to superimpose multiple images on each other, and
can be resolved by installing an XDG MIME database (such as can be
downloaded from
https://sourceforge.net/projects/android-ports-for-gnu-emacs) to
`~/.local/share/mime', as illustrated:

$ cd # (run this within an M-x shell in Emacs.)
$ mkdir -p ~/.local/share/
$ tar xfvz /sdcard/Download/mime-database.tar.gz
$ mv mime-database ~/.local/share/

and restarting Emacs for good measure.

29. Something's missing from this FAQ!

If it's a subject not covered by the Android or Input nodes in the
Emacs manual, or the relevant portions of the Lisp reference manual,
please report a bug. I will then update the manual and this FAQ as I
see fit.