diff options
Diffstat (limited to 'doc/emacs/android.texi')
| -rw-r--r-- | doc/emacs/android.texi | 1140 |
1 files changed, 1140 insertions, 0 deletions
diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi new file mode 100644 index 00000000000..01732961998 --- /dev/null +++ b/doc/emacs/android.texi @@ -0,0 +1,1140 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2023--2024 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 outside 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 this directory, 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 outside the normal Unix 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 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 programs that provide access to +their own files outside both 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 within 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. + + 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 tries its +best to start Emacs for the purpose of running Lisp in batch mode. +However, the approach it takes was devised by reading Android source +code, and is not sanctioned by the Android compatibility definition +documents, so your mileage may vary. + +@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 +maximized or full-screen, and only one window can be displayed at a +time. On larger devices, the system permits simultaneously tiling up +to four windows on the screen. + + Windows on Android do not exist indefinitely after they are created. +Instead, the system may choose to close windows that are not on screen +in order to conserve memory, with the assumption that the program will +save its contents to disk and restore them later, when the user asks +for it to be opened again. As this is obviously not possible with +Emacs, Emacs separates the resources associated with a frame from its +system window. + + Each system window created (including the initial window created +during Emacs startup) is appended to a list of windows that do not +have associated frames. When a frame is created, Emacs looks up any +window within that list, and displays the contents of the frame +within; if there is no window at all, then one is created. Likewise, +when a new window is created by the system, Emacs places the contents +of any frame that is not already displayed within a window inside. +When a frame is closed, the corresponding system window is also +closed. Upon startup, the system creates a window itself (within +which Emacs displays the first window system frame shortly +thereafter.) Emacs differentiates between that window and windows +created on behalf of other frames to determine what to do when the +system window associated with a frame is closed: + +@itemize @bullet +@item +When the system closes the window created during application startup +in order to save memory, Emacs retains the frame for when that window +is created later. + +@item +When the user closes the window created during application startup, +and the window was not previously closed by the system in order to +save resources, Emacs deletes any frame displayed within that window. + +However, on Android 7.0 and later, such frames are not deleted if the +window is closed four or more hours after the window moves into the +background, as the system automatically removes open windows once a +certain period of inactivity elapses when the number of windows retained +by the window manager surpasses a specific threshold, and window +deletion by this mechanism is indistinguishable from window deletion by +the user. Emacs begins to ignore window deletion after two hours less +than the default value of this threshold both to err on the side of +caution, in case the system's record of inactivity and Emacs's differ, +and for the reason that this threshold is open to customization by OS +distributors. + +@item +When the user or the system closes any window created by Emacs on +behalf of a specific frame, Emacs deletes the frame displayed within +that window. +@end itemize + + When the system predates Android 5.0, the window manager will not +accept more than one user-created Emacs window. If frame creation gives +rise to windows in excess of this limit, the window manager will +arbitrarily select one of their number to display, with the rest +remaining invisible until that window is destroyed with its frame. + +@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}, @code{undecorated} and +@code{tool-bar-position} 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. + +@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}. + +@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 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{http://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. |