Next: , Previous: , Up: The Emacs Editor   [Contents][Index]

Appendix H Emacs and Android

Android is a mobile operating system developed by the Open Handset Alliance. This section describes the peculiarities of using Emacs on an Android device running Android 2.2 or later.

Android devices commonly rely a touch screen or digitizer device and virtual keyboard for user input. For more information about using such devices with Emacs, see Touchscreen Input and Virtual Keyboards.

Next: , Up: Emacs and Android   [Contents][Index]

H.1 Android History

Android is an operating system for mobile devices developed by the Open Handset Alliance, a group of companies interested in developing handsets that can run a common set of software. It is supposedly free software.

Like the X Consortium of times past, the Open Handset Alliance believes that “openness” (namely, the regular release of the Android source code) is simply a tool to increase the popularity of the Android platform. Computer companies normally produce proprietary software. The companies in the Open Handset Alliance are no different – most versions of Android installed on devices are proprietary, by virtue of containing proprietary components, that often cannot even be replaced by the user.

Android is not designed to respect users’ freedom. Almost all versions of Android (including some which are supposedly free software) include support for Digital Restrictions Management, technology that is designed to limit users’ ability to copy media to and from their own devices. Most Android devices also come with proprietary Google applications which are required to run the system, and many other Android applications.

Thus, it must be necessary to consider Android proprietary software from a practical standpoint. That is an injustice. If you use Android, we urge you to switch to a free operating system, if only for your freedom’s sake.

We support GNU Emacs on proprietary operating systems because we hope this taste of freedom will inspire users to escape from them.

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.2 Starting Emacs on Android

Emacs is not installed on Android devices from source code or through a package manager. Instead, Emacs is compiled for Android on a different operating system, with the resulting binaries packaged into an archive, that is then transferred to the system and installed.

After being installed, the system places an application icon on the desktop (a.k.a “home screen”.) Emacs then starts up once the application icon is clicked.

During startup, Emacs will display messages in the system log buffer; reading that buffer during start-up requires the Android Debug Bridge (adb) utility to be installed on another computer.

After enabling the “USB Debugging” feature on the Android system, and connecting it via USB to another system with the adb utility installed, the log can be viewed by running the following command on that other system: 

$ adb logcat | grep -E "(android_run_debug_thread|[Ee]macs)"

Assuming that the adb utility is installed on a GNU/Linux or Unix system, follow the steps below to connect to your device.

  1. Enable “developer options” on your device, by going to the “About” page in the system settings application and clicking on the “build version” or “kernel version” items five to seven times.
  2. Open the “developer options” settings page, which should be under the “system” page in the settings application.
  3. Turn on the switch “USB debugging”.
  4. Connect one end of a USB cable to your device, and the other end to your computer’s USB port.
  5. Run the command adb shell on your computer. This will fail or hang because you have not yet granted your computer permission to access the connected device.
  6. Confirm the pop-up displayed on your device asking whether or not it should allow access from your computer.

Depending on the versions of Android and adb installed, there may be other ways to establish a connection. See the official documentation at https://developer.android.com/studio/command-line/adb for more details.

Once Emacs starts up, simply running the command logcat as an asynchronous shell command (see Running Shell Commands from Emacs) will display the log buffer.

Since there is no other way to start the emacsclient program (see Using Emacs as a Server) from another Android program, Emacs provides a wrapper around the emacsclient program, which is registered with the system as an application that can open any file.

When that wrapper is selected as the program with which to open a file, it invokes emacsclient with the options --reuse-frame, --timeout=10, --no-wait, and the name of the file being opened. Then, upon success, the focus is transferred to any open Emacs frame.

However, if Emacs is not running at the time the wrapper is opened, it starts Emacs and gives it the file to open as an argument. Note that if that Emacs in turn does not start the Emacs server, subsequent attempts to open the file with the wrapper will fail.

Some files are given to Emacs as “content identifiers” that the system provides access to independently of the normal filesystem APIs. Emacs uses pseudo-directories named /content/by-authority and /content/by-authority-named to access those files. Do not make any assumptions about the contents of these directories, or try to open files in it yourself.

This feature is not provided on Android 4.3 and earlier, in which case such files are copied to a temporary directory before being opened.

In addition to opening ordinary text files, Emacs also registers its emacsclient wrapper as a program capable of opening “org-protocol” links (see Protocols in The Org Manual).

Furthermore, the wrapper is also registered as a program capable of sending mail to mailto URIs; when it is invoked to open such a URL, it calls the function message-mailto with that URI as its first argument. This feature does not function when the Emacs server is not already running.

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.3 What Files Emacs Can Access on Android

Emacs exposes a special directory on Android systems: the name of the directory is /assets, and it contains the etc, lisp and info directories which are normally installed in /usr/share/emacs directory on GNU and Unix systems. On Android systems, the Lisp emulation of ls (see Emulation of ls on MS-Windows) is also enabled by default, as the ls binary which comes with the system varies by manufacturer and usually does not support all of the features required by Emacs. One copy of ls distributed with some Android systems is even known to lack support for the -l flag.

This directory exists because Android does not extract the contents of application packages on to the file system while unpacking them, but instead requires programs like Emacs to access its contents using a special “asset manager” interface. Here are the peculiarities that result from such an implementation:

Aside from the /assets directory, Android programs normally have access to four other directories. They are:

Despite ordinary installations of Android not having files within the (normally read-only) root directory named content or assets, you may want to access real files by these names if the Android installation in use has been customized. These files will conflict with the aforementioned special directories, but can nevertheless be accessed by writing their names relative to the “parent” directory of the root directory, as so illustrated: /../content, /../assets.

The external storage directory is found at /sdcard. The other directories are not found at any fixed location (but see below), although the app data directory is typically symlinked to /data/data/org.gnu.emacs/files.

Older versions of Android used to place the app library directory under the name lib in the parent of the app data directory. Today, this directory is often placed in a directory with a randomly generated name under /data/app.

For the convenience of scripts running within applications sharing the same user ID as Emacs (which have no access to the exec-directory variable), a fairly considerable effort is made at startup to symlink the application library directory to its traditional location within the parent of the app data directory.

If Emacs is reinstalled and the location of the app library directory consequently changes, that symlink will also be updated to point to its new location the next time Emacs is started by the system.

On Android devices running very old (2.6.29) versions of the Linux kernel, Emacs needs to create files named starting with temp~unlinked in the temporary file directory in order to read from asset files. Do not create files with such names yourself, or they may be overwritten or removed.

On Android 11 and later, the Android system restricts applications from accessing files in the /sdcard directory using file-related system calls such as open and readdir.

This restriction is known as “Scoped Storage”, and supposedly makes the system more secure. Unfortunately, it also means that Emacs cannot access files in those directories, despite holding the necessary permissions. Thankfully, the Open Handset Alliance’s version of Android allows this restriction to be disabled on a per-program basis; the corresponding option in the system settings panel is: 

System -> Apps -> Special App Access -> All files access -> Emacs

After you disable or enable this setting as appropriate and grant Emacs the “Files and Media” permission, it will be able to access files under /sdcard as usual. These settings are not present on some proprietary versions of Android.

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.4 Accessing Files from Other Programs on Android

Android 5.0 introduces a new sort of program, the “document provider”: these programs are small services that provide access to their own files independently of the asset manager and the Unix filesystem. Emacs supports accessing files and directories they provide, placing their files within the directory /content/storage.

Before Emacs is granted access to one of these directories, it must first request the right to access it. This is done by running the command (see Running Commands by Name) android-request-directory-access, which displays a file selection dialog.

If a directory is selected from this dialog, its contents are subsequently made available within a new directory named /content/storage/authority/id, where authority is the name of the document provider, and id is a unique identifier assigned to the directory by the document provider.

Such a directory can be deleted once no longer required by providing its name to the command android-relinquish-directory-access.

The same limitations applied to the /assets directory (see What Files Emacs Can Access on Android) are applied when creating sub-processes within those directories, because they do not exist within the Unix file-system. In addition, although Emacs can normally write and create files inside these directories, it cannot create symlinks or hard links.

Since document providers are allowed to perform expensive network operations to obtain file contents, a file access operation within one of these directories has the potential to take a significant amount of time.

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.5 Running Emacs under Android

From the perspective of users, Android is mostly a single user operating system; however, from the perspective of applications and Emacs, the system is host to an overwhelming number of users.

Each application runs in its own user, with its home directory set to its app data directory (see What Files Emacs Can Access on Android.)41

Each application is also prohibited from accessing many system directories and the app data directories of other applications.

The Emacs distribution also incorporates several binaries. While being executable files, they are packaged as libraries in the library directory, because otherwise the system will not unpack them while Emacs is being installed. This means that instead of emacsclient, Lisp code must specify libemacsclient.so on the command line when starting either of those programs in a subprocess; to determine which names to use, consult the values of the variables etags-program-name, hexl-program-name, emacsclient-program-name, movemail-program-name, ebrowse-program-name, and rcs2log-program-name. See Subprocess Creation in the Emacs Lisp Reference Manual.

The /assets directory containing Emacs start-up files is meant to be inaccessible to processes not directly created by zygote, the system service responsible for starting applications. Since required Lisp is found in the /assets directory, it would thus follow that it is not possible for Emacs to start itself as a subprocess. A special binary named libandroid-emacs.so is provided with Emacs, which is installed into the library directory, and which tries its best to start Emacs for the purpose of running Lisp in batch mode. The approach it takes was devised by reference to Android source code, and is not sanctioned by the Android compatibility definition documents, so your mileage may vary.

Even when the location of the libandroid-emacs.so command is known in advance, special preparation is required to run Emacs from elsewhere than a subprocess of an existing Emacs session, as it must be made to understand the location of resources and shared libraries in or extracted from the installed application package. The OS command pm path org.gnu.emacs will print the location of the application package, though the said command must be invoked in a peculiar manner to satisfy system restrictions on communication between pseudoterminal devices created by user applications and system services such as the package manager, which is to say, with the standard IO streams redirected to a real file or a pipe. This value, once established, must be specified in the environment variables EMACS_CLASS_PATH, so that this sample shell script may be installed as emacs in any location that is accessible: 

#!/system/bin/sh

package_name=`pm path org.gnu.emacs 2>/dev/null </dev/null \
               | sed 's/^package://'`
emacs=
EMACS_CLASS_PATH=$package_name

for libdir in `dirname $package_name`/lib/*; do
  ld_path=${ld_path:+${ld_path}:}$libdir
  test -x "$libdir"/libandroid-emacs.so \
    && emacs="$libdir"/libandroid-emacs.so
done

export EMACS_CLASS_PATH
test -x "$emacs" || exit 1
exec $emacs "$@"

Android 10 and later also prohibit Emacs itself from running executables inside the app data directory, ostensibly out of security concerns. On these systems, Emacs normally applies a workaround; however, this workaround requires running all sub-processes through another subprocess which implements an executable loader and applies process tracing to all its children, which may prove problematic for a variety of reasons. In that case, the workaround can be disabled by changing the variable android-use-exec-loader to nil.

When this workaround is in effect, process IDs retrieved through the process-id function will be that of the executable loader process; its child will belong to the same process group as the loader. Consequently, interrupt-process, and other related functions will work correctly, but using the process ID returned by process-id for other purposes will not.

One ramification of the mechanism by which process tracing is carried out is that job control facilities inside inferior shells (see Interactive Subshell) will not be able to stop processes, and SIGSTOP signals to subprocesses created by Emacs will not take effect.

In addition, Android 12 also terminates subprocesses which are consuming CPU while Emacs itself is in the background. The system judges which processes are consuming too much CPU at intervals of five minutes, and terminates the process that has consumed the most CPU time.

Android 12.1 and Android 13 provide an option to disable this behavior; to use it, enable “USB debugging” (see Starting Emacs on Android) connect the Android system to another computer, and run: 

$ adb shell "settings put global settings_enable_monitor_phantom_procs false"

The “Languages & Input” preferences which apply to the operating system do not influence the C locale set for programs, but are taken into account by Emacs during startup: a locale name is generated from the selected language and regional variant and a language environment (see Language Environments) is selected on that basis, which does not overwrite LANG or other locale-related environment variables. The coding system for language environments set in this fashion is utf-8-unix without exception.

Instead, the LANG environment variable (see General Variables) is set to en_US.utf8 when Emacs starts on Android 5.0 or newer, which induces subprocesses linked against the Android C library to print output sensibly. Earlier versions of Android do not implement locales at all, and on that account, the variable is set to C.

Application processes are treated as disposable entities by the system. When all Emacs frames move to the background, Emacs might be terminated by the system at any time, for the purpose of saving system resources.

On Android 7.1 and earlier, Emacs designates itself a “background service”, which impels the system to avoid killing Emacs unless it is stressed for memory.

Android 8.0 removed the ability for background services to receive such special treatment. However, Emacs applies a workaround: the system considers applications that create a permanent notification to be performing active work, and will avoid killing such applications. Thus, on those systems, Emacs displays a permanent notification for as long as it is running.

Before Android 13, Emacs does not require rights to display notifications. Under Android 13 or later, the notification is hidden until the user accords Emacs such rights. In spite of that, merely attempting to display the notification suffices to avert sudden death; whether the notification is displayed has no bearing on Emacs’s capacity to execute in the background, and it may be disabled without any adverse consequences.

However, it is not guaranteed that the system will not kill Emacs. Although the Open Handset Alliance’s sample implementation of Android behaves correctly, many manufacturers institute additional restrictions on program execution in the background in their proprietary versions of Android. There is a list of such troublesome manufacturers and sometimes workarounds at https://dontkillmyapp.com/.

Android also defines a permissions system that determines what system services Emacs is allowed to access. Programs must specify what permissions they want; what then happens is then subject to the version of Android being used:

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.6 The Android Window System

Android’s window system is unusual in that all windows are reported to applications as maximized or full-screen, and, in the general case, only one window can be displayed at a time. On larger devices, the system permits simultaneously tiling up to four windows on the screen, though in emulators or installations configured for “desktop” systems stacks freely resizable windows as other desktop window managers do.

Windows, or, in system nomenclature, activities, do not exist indefinitely after creation, as the system may choose to pause windows that are not visible in order to conserve memory, on the assumption that the program will save its contents to disk, to be restored when the user selects those windows from the task switcher. Furthermore, a window is created by the operating system at Emacs startup that is afforded special treatment, which Emacs is expected to adopt.

Emacs approaches window management with the general objective of minimizing differences in frame behavior exposed to Lisp from that of frames on ordinary window systems, such as X Windows; the degree to which this goal is actually attained varies by the availability of facilities for window management in the version of Android where it is installed, and operating system policy towards inactive windows. When it is unavoidable that concessions should be made to such policy, Emacs prefers destroying frames to retaining ones with no activities to display them, unless such a frame is the initial frame and therefore displayed in the activity created at startup, which it is possible to open and identify so long as Emacs is yet executing.

Android 5.0 and later support an accurate implementation of window management where frames hold a one-to-one relation to the activities in which they are displayed, enabling deletion of activities in the task switcher to directly affect the frames concerned, and vice versa. There are just two exceptions:

Android 4.4 and earlier provide considerably inferior interfaces inadequate for a complete implementation of window management. On such systems, Emacs substitutes a fairly primitive mechanism where all but the initial frame are deleted when their activities are paused, only a single activity (not counting the activity created at startup) is visible at a time, and unattached frames are displayed in the first unoccupied activity available.

Emacs only supports a limited subset of GUI features on Android; the limitations are as follows:

Emacs does not implement all selection related features supported under the X Window System on Android. For example, only the CLIPBOARD and PRIMARY selections (see “Cut and Paste” Operations on Graphical Displays) are supported, and Emacs is only able to set selections to plain text.

In addition, the Android system itself places certain restrictions on what selection data Emacs can access:

Since the Android system itself has no concept of a primary selection, Emacs provides an emulation instead. This means there is no way to transfer the contents of the primary selection to another application via cut-and-paste.

The volume keys are normally reserved by Emacs and used to provide the ability to quit Emacs without a physical keyboard (see Using Emacs with Virtual Keyboards). However, if you want them to adjust the volume instead, you can set the variable android-pass-multimedia-buttons-to-system to a non-nil value; note that you will no longer be able to quit Emacs using the volume buttons in that case, and that it is generally easier to activate the notification shade or another interface that momentarily deprives Emacs of the keyboard focus while the volume buttons are being depressed.

Emacs is unable to display dialog boxes (see Using Dialog Boxes) while it does not have the input focus on Android 6.0 or later. If this is important to you, this capability can be restored by granting Emacs permission to display over other programs. On most systems, this can be done from the following Settings menu: 

System -> Apps -> Emacs -> More -> Display over other apps

There is a direct relation between physical modifier keys and Emacs modifiers (see Modifier Keys) reported within key events, subject to a single exception: if Alt on your keyboard is depressed, then the Meta modifier will be reported by Emacs in its place, and vice versa. This irregularity is since most keyboards possess no special Meta key, and the Alt modifier is seldom employed in Emacs.

Bear in mind that Android uses a different name for the Super modifier: it is referred to as SYM on Android keyboards and within the Settings keymap menu.

Android input methods have a penchant for irritating users by silently discarding key sequences containing C-SPC during the event filtering process, that they normally have no real application for such key sequences notwithstanding. By default, Emacs intercepts these key sequences before they can be filtered by the input method.

If this proves unwanted (for instance, if the input method treats C-SPC as a shortcut key for switching languages), it can be disabled by setting the variable android-intercept-control-space to nil.

The keyboard bell installed within Android systems takes the form of a vibrating element that is activated for a number of milliseconds whenever the bell is rung. The duration of this vibration can be customized through altering the variable android-keyboard-bell-duration to any value between 10 and 1000.

Color-related characteristics of the display are not automatically detectable on Android, so the variable android-display-planes should be configured to a suitable value if Emacs is to realize faces and images in a manner consistent with the true visual attributes of a grayscale or monochrome display: to 8 for the former class of display, and 1 for the latter, which will, respectively, force all colors to be rendered in 256 grays, or in monochrome. As this variable is processed at the time the display connection is established, customizations will not take effect unless they be performed from early-init.el (see The Early Init File).

The value of this variable does not affect anti-aliasing in the font driver, as monochrome displays nevertheless expect Emacs to provide antialiased text, which they receive after it is processed into bitmap data by the display driver.

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.7 Font Backends and Selection under Android

Emacs supports two font backends under Android: they are respectively named sfnt-android and android.

Upon startup, Emacs enumerates all the TrueType format fonts in the directories /system/fonts and /product/fonts, and the fonts directory (user fonts directory) inside the Emacs home directory. Emacs assumes there will always be a font named “Droid Sans Mono”, and then defaults to using this font. These fonts are then displayed by the sfnt-android font driver.

This font driver is presently without support for OpenType or color fonts; hence, only a subset of the fonts installed on any given system are available to Emacs. If you are interested in lifting this limitation, please contact .

If the sfnt-android font driver fails to find any fonts at all, Emacs falls back to the android font driver. This is a very poor font driver, consequent upon limitations and inaccuracies in the font metrics provided by the Android platform. In that case, Emacs uses the “Monospace” typeface configured on your system; this should always be Droid Sans Mono.

As on X systems, Emacs supports distortable fonts under Android. These fonts (also termed “TrueType GX fonts”, “variable fonts”, and “multiple master fonts”) provide multiple different styles (“Bold”, “Italic”, and the like) using a single font file.

When a user-installed distortable font is found, each style that a previously discovered font provided will no longer be used. In addition, any previously installed distortable fonts with the same family name are also disregarded, provided that the new distortable font supplies a superset of the styles furnished by the previously installed font. When a conventional font is found, any previous conventional font with the same style and family will be removed; distortable fonts with the same family will no longer be used to provide that style.

Emacs generally assumes the presence of font families named ‘Monospace’, ‘Monospace Serif’, ‘Sans Serif’, and ‘DejaVu Serif’. Since Android does not provide any fonts by these names, Emacs modifies requests for them to request one of a corresponding set of font families distributed with Android.

To change either the set of font families subject to replacement, or that by which they are replaced, modify the variable sfnt-default-family-alist; then, restart Emacs. Bear in mind that this is usually unwarranted, with customizations to the default or variable-pitch faces better made through modifying their definitions (see Customizing Faces).

Next: , Previous: , Up: Emacs and Android   [Contents][Index]

H.8 Troubleshooting Startup Problems on Android

Since Android has no command line, there is normally no way to specify command-line arguments when starting Emacs. This is very nasty when you make a mistake in your Emacs initialization files that prevents Emacs from starting up at all, as the system generally prohibits other programs from accessing Emacs’s home directory. See Initial Options.

However, Emacs can be started with the equivalent of either the option --quick, or --debug-init through a special preferences screen. Under Android 7.0 and later, this can be accessed through the Emacs “app info” page in the system settings program; on older systems, this is displayed as a separate icon on the desktop labeled “Emacs options”.

Consult the manufacturer of your device for more details, as how to do this varies by device.

The first time any given copy of Emacs starts on a device, it spends a while loading the preloaded Lisp files which normally come with Emacs. This produces a “dump file” (see Initial Options) in the files directory, containing an identifier unique to that copy of Emacs.

The next time that same copy of Emacs starts up, it simply loads the data contained in that dump file, greatly reducing start up time.

If by some unforeseen circumstance the dump file is corrupted, Emacs can crash. If that happens, the dump file stored in the Emacs files directory can be erased through the preferences screen described above.

Emacs supports an alternative method of rescuing broken Emacs installations on Android 4.4 and later: Emacs exports a “documents provider” which accesses the contents of Emacs’s home directory, that can then be accessed by any file manager program.

If you can find out how to open that documents provider in the file manager that comes with your device, you can rename, delete, or edit your initialization or dump files from there instead.

Previous: , Up: Emacs and Android   [Contents][Index]

H.9 Installing Extra Software on Android

An exceptionally limited set of Unix-like command line tools is distributed alongside default installations of Android. Several projects exist to augment this selection, providing options that range from improved reproductions of Unix command-line utilities to package repositories providing extensive collections of free GNU and Unix software.

Busybox provides Unix utilities and limited replicas of certain popular GNU programs such as wget in a single statically-linked Linux binary, which is capable of running under Android.

Termux provides a package manager based on the Debian project’s dpkg system and a set of package repositories containing substantial amounts of free software for Unix systems, including compilers, debuggers, and runtimes for languages such as C, C++, Java, Python and Common Lisp. These packages are customarily installed from within a purpose-built terminal emulator application, but access is also granted to Emacs when it is built with the same application signing key, and its “shared user ID” is set to the same package name, as that of the terminal emulator program. The file java/INSTALL within the Emacs distribution illustrates how to build Emacs in this fashion.

termux-packages provides the package definitions used by Termux to generate their package repositories, which may also be independently compiled for installation within Emacs’s home directory.

In addition to the projects mentioned above, statically linked binaries for most Linux kernel-based systems can also be run on Android.

Emacs can be configured with support for viewing SVG image files by means of the librsvg library. In SVG files, there may be references to other images on the file-system, whose format librsvg cannot detect by default, and which will be rendered as blank squares unless an XDG-compliant MIME database is installed into the directory .local/share/mime within your home directory.

As the XDG shared-mime-info tools must be available to generate such a database, it is recommended to produce this database in a temporary directory on a GNU/Linux or Unix system, before transferring the same to the recipient Android device. With the latest release of shared-mime-info installed, create a temporary directory in which to generate the MIME database, copy the default freedesktop.org.in MIME catalog to a directory named packages, and execute update-mime-info to generate the database: 

$ mkdir -p my-mime-database/packages
$ cp /usr/share/mime/packages/freedesktop.org.xml my-mime-database/packages
$ update-mime-info my-mime-database

This may print a series of notices stating that the MIME database specified is not in the search path on your host system, which are of no consequence. Proceed by transferring the contents of the MIME database to the recipient system, e.g., to /sdcard/Download/my-mime-database.tar.gz: 

$ cd; mkdir -p .local/share
$ tar xfz /sdcard/Download/my-mime-database.tar.gz
$ mv my-mime-database .local/share/mime
$ rm /sdcard/Download/my-mime-database.tar.gz

If your Emacs session has already attempted to display an SVG image with embeds, Emacs must be restarted before the new MIME database will enter into effect.

Footnotes

(41)

Except in cases where a “shared user ID” is specified and other applications signed using the same “package signing key” are installed, in which case Emacs runs as the same user and has access to the same files as each of the aforementioned applications.

Next: , Previous: , Up: The Emacs Editor   [Contents][Index]