@c This is part of the Emacs manual.
@c Copyright (C) 2023--2025 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Android
@appendix Emacs and Android
@cindex 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, @pxref{Other Input}.

@menu
* What is Android?::            Preamble.
* Android Startup::             Starting up Emacs on Android.
* Android File System::         The Android file system.
* Android Document Providers::  Accessing files from other programs.
* Android Environment::         Running Emacs under Android.
* Android Windowing::           The Android window system.
* Android Fonts::               Font selection under Android.
* Android Troubleshooting::     Dealing with problems.
* Android Software::            Getting extra software.
@end menu

@node What is Android?
@section 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.

@node Android Startup
@section 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.

@cindex ``adb logcat''

  During startup, Emacs will display messages in the system log
buffer; reading that buffer during start-up requires the Android Debug
Bridge (@command{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 @command{adb}
utility installed, the log can be viewed by running the following
command on that other system:

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

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

@enumerate
@item
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.

@item
Open the ``developer options'' settings page, which should be under
the ``system'' page in the settings application.

@item
Turn on the switch ``USB debugging''.

@item
Connect one end of a USB cable to your device, and the other end to
your computer's USB port.

@item
Run the command @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.

@item
Confirm the pop-up displayed on your device asking whether or not it
should allow access from your computer.
@end enumerate

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

  Once Emacs starts up, simply running the command @command{logcat} as
an asynchronous shell command (@pxref{Shell}) will display the log
buffer.

@cindex emacsclient wrapper, android
  Since there is no other way to start the @command{emacsclient}
program (@pxref{Emacs Server}) from another Android program, Emacs
provides a wrapper around the @command{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 @command{emacsclient} with the options
@command{--reuse-frame}, @command{--timeout=10}, @command{--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.

@cindex /content/by-authority directory, android
@cindex /content/by-authority-named directory, android
  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 @file{/content/by-authority} and
@file{/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.

@cindex ``org-protocol'' links, android
  In addition to opening ordinary text files, Emacs also registers its
@command{emacsclient} wrapper as a program capable of opening
``org-protocol'' links (@pxref{Protocols,,,org, The Org Manual}).

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

@node Android File System
@section What Files Emacs Can Access on Android
@cindex /assets directory, android

  Emacs exposes a special directory on Android systems: the name of
the directory is @file{/assets}, and it contains the @file{etc},
@file{lisp} and @file{info} directories which are normally installed
in @file{/usr/share/emacs} directory on GNU and Unix systems.  On
Android systems, the Lisp emulation of @command{ls} (@pxref{ls in
Lisp}) is also enabled by default, as the @command{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
@command{ls} distributed with some Android systems is even known to
lack support for the @code{-l} flag.

@cindex limitations of the /assets directory

  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:

@itemize @bullet
@item
Subprocesses (such as @command{ls}) can not run from the
@file{/assets} directory; if you try to run a subprocess with
@code{current-directory} set to @file{/assets},
@file{/content/storage} or a subdirectory thereof, it will run from
the home directory instead.

@item
There are no @file{.} and @file{..} directories inside the
@file{/assets} or @file{/content} directory.

@item
Files in the @file{/assets} directory are always read only, and may be
read in to memory more than once each time they are opened.
@end itemize

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

@itemize @bullet
@item
The @dfn{app data} directory.  This also serves as the home directory
for Emacs, and is always accessible read-write.

@item
The @dfn{app library} directory.  This is automatically appended to
@code{exec-path} and made @code{exec-directory} upon startup, and
contains utility executables alongside Emacs itself.

@item
The @dfn{external storage} directory.  This is accessible to Emacs
when the user grants the ``Files and Media'' permission to Emacs via
system settings.

@item
Directories provided by @dfn{document providers} on Android 5.0 and
later.  These directories exist independently of the Unix virtual
filesystem, containing files provided by external programs
(@pxref{Android Document Providers}.)
@end itemize

  Despite ordinary installations of Android not having files within
the (normally read-only) root directory named @file{content} or
@file{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:
@file{/../content}, @file{/../assets}.

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

@cindex app library directory, android
@cindex where is emacsclient under android
  Older versions of Android used to place the app library directory
under the name @file{lib} in the parent of the app data directory.
Today, this directory is often placed in a directory with a randomly
generated name under @file{/data/app}.

  For the convenience of scripts running within applications sharing
the same user ID as Emacs (which have no access to the
@code{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.

@cindex temp~unlinked.NNNN files, Android
  On Android devices running very old (2.6.29) versions of the Linux
kernel, Emacs needs to create files named starting with
@file{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.

@cindex file system limitations, Android 11
  On Android 11 and later, the Android system restricts applications
from accessing files in the @file{/sdcard} directory using
file-related system calls such as @code{open} and @code{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:

@example
System -> Apps -> Special App Access -> All files access -> Emacs
@end example

  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 @file{/sdcard} as usual.  These settings are not present
on some proprietary versions of Android.

@node Android Document Providers
@section Accessing Files from Other Programs on Android
@cindex document providers, Android
@cindex /content/storage directory, 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
@file{/content/storage}.

@findex android-request-directory-access
  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 (@pxref{M-x}) @code{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
@file{/content/storage/@var{authority}/@var{id}}, where @var{authority}
is the name of the document provider, and @var{id} is a unique
identifier assigned to the directory by the document provider.

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

  The same limitations applied to the @file{/assets} directory
(@pxref{Android File System}) 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.

@node Android Environment
@section 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 (@pxref{Android File
System}.)@footnote{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.}

  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 @code{ctags} or
@code{emacsclient}, Lisp code must specify @code{libctags.so} or
@code{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 @code{ctags-program-name},
@code{etags-program-name}, @code{hexl-program-name},
@code{emacsclient-program-name}, @code{movemail-program-name},
@code{ebrowse-program-name}, and @code{rcs2log-program-name}.
@xref{Subprocess Creation,,, elisp, the Emacs Lisp Reference Manual}.

  The @file{/assets} directory containing Emacs start-up files is meant
to be inaccessible to processes not directly created by @code{zygote},
the system service responsible for starting applications.  Since
required Lisp is found in the @file{/assets} directory, it would thus
follow that it is not possible for Emacs to start itself as a
subprocess.  A special binary named @command{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.

@cindex EMACS_CLASS_PATH environment variable, Android
  Even when the location of the @command{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
@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
@code{EMACS_CLASS_PATH}, so that this sample shell script may be
installed as @code{emacs} in any location that is accessible:

@example
#!/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 "$@@"
@end example

@cindex call-process, Android
@vindex android-use-exec-loader
  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 @code{android-use-exec-loader} to @code{nil}.

  When this workaround is in effect, process IDs retrieved through the
@code{process-id} function will be that of the executable loader
process; its child will belong to the same process group as the
loader.  Consequently, @code{interrupt-process}, and other related
functions will work correctly, but using the process ID returned by
@code{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
(@pxref{Interactive Shell}) will not be able to stop processes, and
@code{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'' (@pxref{Android
Startup}) connect the Android system to another computer, and run:

@example
$ adb shell "settings put global settings_enable_monitor_phantom_procs false"
@end example

@cindex system language settings, Android
  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
(@pxref{Language Environments}) is selected on that basis, which does
not overwrite @code{LANG} or other locale-related environment
variables.  The coding system for language environments set in this
fashion is @code{utf-8-unix} without exception.

@cindex C locale settings, Android
  Instead, the @code{LANG} environment variable (@pxref{General
Variables}) is set to @code{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
@code{C}.

@cindex running emacs in the background, android
@cindex emacs killed, android
@cindex emacs in the background, android

  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
@url{https://dontkillmyapp.com/}.

@cindex permissions under android
@cindex external storage, android

  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:

@itemize @bullet
@item
Under more or less recent releases of Android, such as Android 6.0 and
later, Emacs only receives the following permissions upon installation,
subject to the presence or absence of individual permissions in the
version of Android installed:

@itemize @minus
@item
@code{android.permission.ACCESS_ADSERVICES_AD_ID}
@item
@code{android.permission.ACCESS_ADSERVICES_ATTRIBUTION}
@item
@code{android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE}
@item
@code{android.permission.ACCESS_ADSERVICES_TOPICS}
@item
@code{android.permission.ACCESS_LOCATION_EXTRA_COMMANDS}
@item
@code{android.permission.ACCESS_NETWORK_STATE}
@item
@code{android.permission.ACCESS_NOTIFICATION_POLICY}
@item
@code{android.permission.ACCESS_WIFI_STATE}
@item
@code{android.permission.AUTHENTICATE_ACCOUNTS}
@item
@code{android.permission.BLUETOOTH}
@item
@code{android.permission.BLUETOOTH_ADMIN}
@item
@code{android.permission.BROADCAST_STICKY}
@item
@code{android.permission.CALL_COMPANION_APP}
@item
@code{android.permission.CHANGE_NETWORK_STATE}
@item
@code{android.permission.CHANGE_WIFI_MULTICAST_STATE}
@item
@code{android.permission.CHANGE_WIFI_STATE}
@item
@code{android.permission.CREDENTIAL_MANAGER_QUERY_CANDIDATE_CREDENTIALS}
@item
@code{android.permission.CREDENTIAL_MANAGER_SET_ALLOWED_PROVIDERS}
@item
@code{android.permission.CREDENTIAL_MANAGER_SET_ORIGIN}
@item
@code{android.permission.DELIVER_COMPANION_MESSAGES}
@item
@code{android.permission.DETECT_SCREEN_CAPTURE}
@item
@code{android.permission.DISABLE_KEYGUARD}
@item
@code{android.permission.ENFORCE_UPDATE_OWNERSHIP}
@item
@code{android.permission.EXPAND_STATUS_BAR}
@item
@code{android.permission.FLASHLIGHT}
@item
@code{android.permission.FOREGROUND_SERVICE}
@item
@code{android.permission.FOREGROUND_SERVICE_CAMERA}
@item
@code{android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE}
@item
@code{android.permission.FOREGROUND_SERVICE_DATA_SYNC}
@item
@code{android.permission.FOREGROUND_SERVICE_FILE_MANAGEMENT}
@item
@code{android.permission.FOREGROUND_SERVICE_HEALTH}
@item
@code{android.permission.FOREGROUND_SERVICE_LOCATION}
@item
@code{android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK}
@item
@code{android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION}
@item
@code{android.permission.FOREGROUND_SERVICE_MICROPHONE}
@item
@code{android.permission.FOREGROUND_SERVICE_PHONE_CALL}
@item
@code{android.permission.FOREGROUND_SERVICE_REMOTE_MESSAGING}
@item
@code{android.permission.FOREGROUND_SERVICE_SPECIAL_USE}
@item
@code{android.permission.FOREGROUND_SERVICE_SYSTEM_EXEMPTED}
@item
@code{android.permission.GET_PACKAGE_SIZE}
@item
@code{android.permission.GET_TASKS}
@item
@code{android.permission.HIDE_OVERLAY_WINDOWS}
@item
@code{android.permission.HIGH_SAMPLING_RATE_SENSORS}
@item
@code{android.permission.INTERNET}
@item
@code{android.permission.KILL_BACKGROUND_PROCESSES}
@item
@code{android.permission.MANAGE_ACCOUNTS}
@item
@code{android.permission.MANAGE_OWN_CALLS}
@item
@code{android.permission.MODIFY_AUDIO_SETTINGS}
@item
@code{android.permission.NFC}
@item
@code{android.permission.NFC_PREFERRED_PAYMENT_INFO}
@item
@code{android.permission.NFC_TRANSACTION_EVENT}
@item
@code{android.permission.PERSISTENT_ACTIVITY}
@item
@code{android.permission.QUERY_ALL_PACKAGES}
@item
@code{android.permission.READ_BASIC_PHONE_STATE}
@item
@code{android.permission.READ_INSTALL_SESSIONS}
@item
@code{android.permission.READ_NEARBY_STREAMING_POLICY}
@item
@code{android.permission.READ_PROFILE}
@item
@code{android.permission.READ_SOCIAL_STREAM}
@item
@code{android.permission.READ_SYNC_SETTINGS}
@item
@code{android.permission.READ_SYNC_STATS}
@item
@code{android.permission.READ_USER_DICTIONARY}
@item
@code{android.permission.RECEIVE_BOOT_COMPLETED}
@item
@code{android.permission.REORDER_TASKS}
@item
@code{android.permission.REQUEST_COMPANION_PROFILE_GLASSES}
@item
@code{android.permission.REQUEST_COMPANION_PROFILE_WATCH}
@item
@code{android.permission.REQUEST_COMPANION_RUN_IN_BACKGROUND}
@item
@code{android.permission.REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND}
@item
@code{android.permission.REQUEST_COMPANION_USE_DATA_IN_BACKGROUND}
@item
@code{android.permission.REQUEST_DELETE_PACKAGES}
@item
@code{android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS}
@item
@code{android.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE}
@item
@code{android.permission.REQUEST_PASSWORD_COMPLEXITY}
@item
@code{android.permission.RESTART_PACKAGES}
@item
@code{android.permission.RUN_USER_INITIATED_JOBS}
@item
@code{android.permission.SET_WALLPAPER}
@item
@code{android.permission.SET_WALLPAPER_HINTS}
@item
@code{android.permission.SUBSCRIBED_FEEDS_READ}
@item
@code{android.permission.SUBSCRIBED_FEEDS_WRITE}
@item
@code{android.permission.TRANSMIT_IR}
@item
@code{android.permission.UPDATE_PACKAGES_WITHOUT_USER_ACTION}
@item
@code{android.permission.USE_BIOMETRIC}
@item
@code{android.permission.USE_CREDENTIALS}
@item
@code{android.permission.USE_EXACT_ALARM}
@item
@code{android.permission.USE_FINGERPRINT}
@item
@code{android.permission.USE_FULL_SCREEN_INTENT}
@item
@code{android.permission.VIBRATE}
@item
@code{android.permission.WAKE_LOCK}
@item
@code{android.permission.WRITE_PROFILE}
@item
@code{android.permission.WRITE_SMS}
@item
@code{android.permission.WRITE_SOCIAL_STREAM}
@item
@code{android.permission.WRITE_SYNC_SETTINGS}
@item
@code{android.permission.WRITE_USER_DICTIONARY}
@end itemize

Other permissions must be granted by the user from the system settings
application.  Consult the manufacturer of your device for more details,
as how to do this varies by device.

@item
On Android 5.1 and earlier, Emacs automatically receives the following
permissions it has requested upon being installed:

@itemize @minus
@item
@code{android.permission.ACCESS_COARSE_LOCATION}
@item
@code{android.permission.ACCESS_FINE_LOCATION}
@item
@code{android.permission.BODY_SENSORS}
@item
@code{android.permission.CALL_PHONE}
@item
@code{android.permission.CAMERA}
@item
@code{android.permission.CAPTURE_CONSENTLESS_BUGREPORT_ON_USERDEBUG_BUILD}
@item
@code{android.permission.GET_ACCOUNTS}
@item
@code{android.permission.POST_NOTIFICATIONS}
@item
@code{android.permission.PROCESS_OUTGOING_CALLS}
@item
@code{android.permission.READ_CALENDAR}
@item
@code{android.permission.READ_CALL_LOG}
@item
@code{android.permission.READ_CELL_BROADCASTS}
@item
@code{android.permission.READ_CONTACTS}
@item
@code{android.permission.READ_EXTERNAL_STORAGE}
@item
@code{android.permission.READ_PHONE_NUMBERS}
@item
@code{android.permission.READ_PHONE_STATE}
@item
@code{android.permission.READ_SMS}
@item
@code{android.permission.RECEIVE_MMS}
@item
@code{android.permission.RECEIVE_SMS}
@item
@code{android.permission.RECEIVE_WAP_PUSH}
@item
@code{android.permission.RECORD_AUDIO}
@item
@code{android.permission.REQUEST_INSTALL_PACKAGES}
@item
@code{android.permission.SEND_SMS}
@item
@code{android.permission.SMS_FINANCIAL_TRANSACTIONS}
@item
@code{android.permission.SYSTEM_ALERT_WINDOW}
@item
@code{android.permission.WRITE_CALENDAR}
@item
@code{android.permission.WRITE_CALL_LOG}
@item
@code{android.permission.WRITE_CONTACTS}
@item
@code{android.permission.WRITE_EXTERNAL_STORAGE}
@item
@code{android.permission.WRITE_SETTINGS}
@item
@code{android.permission.ACCESS_LOCATION_EXTRA_COMMANDS}
@item
@code{android.permission.ACCESS_NETWORK_STATE}
@item
@code{android.permission.ACCESS_WIFI_STATE}
@item
@code{android.permission.BLUETOOTH}
@item
@code{android.permission.BLUETOOTH_ADMIN}
@item
@code{android.permission.BROADCAST_STICKY}
@item
@code{android.permission.CHANGE_NETWORK_STATE}
@item
@code{android.permission.CHANGE_WIFI_MULTICAST_STATE}
@item
@code{android.permission.CHANGE_WIFI_STATE}
@item
@code{android.permission.DISABLE_KEYGUARD}
@item
@code{android.permission.EXPAND_STATUS_BAR}
@item
@code{android.permission.FLASHLIGHT}
@item
@code{android.permission.GET_PACKAGE_SIZE}
@item
@code{android.permission.GET_TASKS}
@item
@code{android.permission.INTERNET}
@item
@code{android.permission.KILL_BACKGROUND_PROCESSES}
@item
@code{android.permission.MODIFY_AUDIO_SETTINGS}
@item
@code{android.permission.NFC}
@item
@code{android.permission.PERSISTENT_ACTIVITY}
@item
@code{android.permission.QUERY_ALL_PACKAGES}
@item
@code{android.permission.READ_BASIC_PHONE_STATE}
@item
@code{android.permission.READ_SYNC_SETTINGS}
@item
@code{android.permission.READ_SYNC_STATS}
@item
@code{android.permission.READ_USER_DICTIONARY}
@item
@code{android.permission.RECEIVE_BOOT_COMPLETED}
@item
@code{android.permission.REORDER_TASKS}
@item
@code{android.permission.REQUEST_DELETE_PACKAGES}
@item
@code{android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS}
@item
@code{android.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE}
@item
@code{android.permission.RESTART_PACKAGES}
@item
@code{android.permission.SET_WALLPAPER}
@item
@code{android.permission.SET_WALLPAPER_HINTS}
@item
@code{android.permission.TRANSMIT_IR}
@item
@code{android.permission.VIBRATE}
@item
@code{android.permission.WAKE_LOCK}
@item
@code{android.permission.WRITE_SYNC_SETTINGS}
@item
@code{android.permission.WRITE_USER_DICTIONARY}
@end itemize

While most of these permissions are left unused by Emacs itself, they
are declared by Emacs as they could be useful for other programs; for
example, the permission to access contacts may be useful for EUDC.
@end itemize

@node Android Windowing
@section 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.

@cindex frames and windows, Android 5.0
  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:

@itemize @bullet
@item
After the system pauses an activity that remains in the task switcher in
response to inactivity, removing it from the task switcher while it
remains in its inactive state will not delete the frame inside, as Emacs
is not notified of the deletion of its activities in such circumstances.
The frame will be deleted upon the next window management operation that
prompts an examination of the list of live windows.  Likewise, an
inactive activity displaying a frame will not be immediately deleted
with its frame, but will be if it is selected from the window list or
upon another examination of the window list.

@item
Any frame besides the initial frame might be deleted after 4 to 6 hours
of inactivity in the background, if it is removed by the system in
``trimming'' the task switcher of excess, and presumably unwanted,
tasks; the initial frame is exempt from this treatment because it can be
reopened otherwise than from the task switcher, but as deletion by this
mechanism is indistinguishable from legitimate user action to remove
activities from the task switcher, the latter will also be ignored by
the initial frame after a 4-hour interval elapses from the time of last
activity.
@end itemize

@cindex frames and windows, Android 4.4
@cindex frames and windows, Android 2.2
  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.

@cindex windowing limitations, android
@cindex frame parameters, android
Emacs only supports a limited subset of GUI features on Android; the
limitations are as follows:

@itemize @bullet
@item
Scroll bars are not supported, as they are close to useless on Android
devices.

@item
The @code{alpha}, @code{alpha-background}, @code{z-group},
@code{override-redirect}, @code{mouse-color}, @code{title},
@code{wait-for-wm}, @code{sticky}, and @code{undecorated} frame
parameters (@pxref{Frame Parameters,,, elisp, the Emacs Lisp Reference
Manual}) are unsupported.

@item
On Android 4.0 and earlier, the @code{fullscreen} frame parameter is
always @code{maximized} for top-level frames; on later versions of
Android, it can also be @code{fullscreen}.
@end itemize

@cindex selections, android
@cindex android clipboard
  Emacs does not implement all selection related features supported
under the X Window System on Android.  For example, only the
@code{CLIPBOARD} and @code{PRIMARY} selections (@pxref{Cut and Paste})
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:

@itemize @bullet
@item
On Android 2.3 and earlier, the function @code{gui-selection-owner-p}
always returns @code{nil} for the clipboard selection.

@item
Between Android 3.0 and Android 9.0, Emacs is able to access the
clipboard whenever it wants, and @code{gui-selection-owner-p} always
returns accurate results.

@item
Under Android 10.0 and later, Emacs can only access clipboard data
when one of its frames has the input focus, and
@code{gui-selection-owner-p} always returns @code{nil} for the
clipboard selection.
@end itemize

  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.

@vindex android-pass-multimedia-buttons-to-system
@cindex volume/multimedia buttons, Android
  The volume keys are normally reserved by Emacs and used to provide the
ability to quit Emacs without a physical keyboard (@pxref{On-Screen
Keyboards}).  However, if you want them to adjust the volume instead,
you can set the variable
@code{android-pass-multimedia-buttons-to-system} to a non-@code{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.

@cindex dialog boxes, android
  Emacs is unable to display dialog boxes (@pxref{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:

@example
System -> Apps -> Emacs -> More -> Display over other apps
@end example

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

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

@vindex android-intercept-control-space
@cindex @kbd{C-SPC} interception, android
  Android input methods have a penchant for irritating users by
silently discarding key sequences containing @kbd{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
@kbd{C-SPC} as a shortcut key for switching languages), it can be
disabled by setting the variable
@code{android-intercept-control-space} to @code{nil}.

@vindex android-keyboard-bell-duration
@cindex keyboard bell, android
  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
@code{android-keyboard-bell-duration} to any value between @code{10}
and @code{1000}.

@vindex android-display-planes
@cindex visual class, Android
@cindex display color space, Android
  Color-related characteristics of the display are not automatically
detectable on Android, so the variable @code{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 @code{8} for the former class of
display, and @code{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
@code{early-init.el} (@pxref{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.

@node Android Fonts
@section Font Backends and Selection under Android
@cindex fonts, android

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

  Upon startup, Emacs enumerates all the TrueType format fonts in the
directories @file{/system/fonts} and @file{/product/fonts}, and the
@file{fonts} directory (@dfn{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 @code{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 @email{emacs-devel@@gnu.org}.

  If the @code{sfnt-android} font driver fails to find any fonts at
all, Emacs falls back to the @code{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.

@cindex TrueType GX fonts, android
@cindex distortable fonts, android

  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.

@cindex default font families, Android
@vindex sfnt-default-family-alist

  Emacs generally assumes the presence of font families named
@samp{Monospace}, @samp{Monospace Serif}, @samp{Sans Serif}, and
@samp{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
@code{sfnt-default-family-alist}; then, restart Emacs.  Bear in mind
that this is usually unwarranted, with customizations to the default
or @code{variable-pitch} faces better made through modifying their
definitions (@pxref{Face Customization}).

@node Android Troubleshooting
@section Troubleshooting Startup Problems on Android
@cindex troubleshooting, android

@cindex emacs -Q, android
@cindex emacs --debug-init, 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.
@xref{Initial Options}.

  However, Emacs can be started with the equivalent of either the
option @code{--quick}, or @code{--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.

@cindex dumping, android
  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'' (@pxref{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.

@cindex accessing Emacs directories, Android
  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.

@node Android Software
@section Installing Extra Software on Android
@cindex installing extra software on Android
@cindex installing Unix 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.

  @uref{https://busybox.net, Busybox} provides Unix utilities and
limited replicas of certain popular GNU programs such as
@command{wget} in a single statically-linked Linux binary, which is
capable of running under Android.

  @uref{https://termux.dev, Termux} provides a package manager based
on the Debian project's @command{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 @file{java/INSTALL} within the Emacs distribution illustrates how
to build Emacs in this fashion.

  @uref{https://github.com/termux/termux-packages, 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.