From 190de0f9ed8ef484db9433da115c5c617af105a1 Mon Sep 17 00:00:00 2001 From: Po Lu Date: Fri, 12 Jul 2024 11:59:09 +0800 Subject: [PATCH] Document means of executing Emacs from unrelated Android applications * doc/emacs/android.texi (Android Environment): Document significance, effect and purpose of EMACS_CLASS_PATH and EMACS_LD_LIBRARY_PATH, and the utility of `pm path org.gnu.emacs'. (cherry picked from commit a5ef9e25680d490e2a453e5ed518aba8f4560b2d) --- doc/emacs/android.texi | 63 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 11 deletions(-) diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi index cfa29d59f36..250e07d9279 100644 --- a/doc/emacs/android.texi +++ b/doc/emacs/android.texi @@ -364,17 +364,58 @@ consult the values of the variables @code{ctags-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. + 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 configuration 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, and the adjacent @file{lib} directory will hold +shared libraries extracted from the same, 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. Such values, once established, must be specified in the +environment variables @code{EMACS_CLASS_PATH} and +@code{EMACS_LD_LIBRARY_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